# Colors (/docs/colors)





## Overview [#overview]

Tokens mirror [Tailwind color conventions](https://tailwindcss.com/docs/colors#core-concepts), so names align with utility classes and stay predictable in your project.

## Core concepts [#core-concepts]

The UI draws from one of nine neutral gray scales. The scale you choose sets backgrounds, borders, and muted tones for the whole theme.

The default palette is `neutral`, anchored at `neutral-50` in light mode and `neutral-950` in dark mode. Preview another scale with the swatches below:

<ColorsConcept />

Click a swatch to switch the neutral scale and preview the theme across the docs. Subtle differences between grays are easiest to judge in dark mode.

<Alert variant="info">
  <InfoIcon />

  <AlertTitle>
    Build your own color palette
  </AlertTitle>

  <AlertDescription>
    Try the [Theme editor](/themes) to visually customize primary, neutral colors and radius.
  </AlertDescription>
</Alert>

## Theme Tokens [#theme-tokens]

These tokens live in your CSS file under `:root` and `.dark`.

### background / foreground [#background--foreground]

The default app background and text color for the page shell, page sections, and default text.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-background" /></span> `--background`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-foreground" /></span> `--foreground`

### card [#card]

Elevated surfaces and the content inside them, including Card, dashboard panels, and settings panels.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-card" /></span> `--card`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-card-foreground" /></span> `--card-foreground`

### popover [#popover]

Floating surfaces and the content inside them, such as Popover, DropdownMenu, ContextMenu, and other overlays.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-popover" /></span> `--popover`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-popover-foreground" /></span> `--popover-foreground`

### primary [#primary]

High-emphasis actions and brand surfaces, including the default Button, selected states, badges, and active accents.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-primary" /></span> `--primary`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-primary-foreground" /></span> `--primary-foreground`

### secondary [#secondary]

Lower-emphasis filled actions and supporting surfaces, such as secondary buttons, secondary badges, and supporting UI.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-secondary" /></span> `--secondary`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-secondary-foreground" /></span> `--secondary-foreground`

### muted [#muted]

Subtle surfaces and lower-emphasis content for descriptions, placeholders, empty states, helper text, and subdued surfaces.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-muted" /></span> `--muted`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-muted-foreground" /></span> `--muted-foreground`

### accent [#accent]

Interactive hover, focus, and active surfaces for ghost buttons, menu highlight states, hovered rows, and selected items.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-accent" /></span> `--accent`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-accent-foreground" /></span> `--accent-foreground`

### destructive [#destructive]

Destructive actions and error emphasis for destructive buttons, invalid states, and destructive menu items.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-destructive" /></span> `--destructive`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-destructive-foreground" /></span> `--destructive-foreground`

### info [#info]

Informational actions and emphasis for informational buttons, badges, alerts, status, etc.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-info" /></span> `--info`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-info-foreground" /></span> `--info-foreground`

### success [#success]

Success actions and emphasis for success buttons, badges, alerts, status, etc.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-success" /></span> `--success`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-success-foreground" /></span> `--success-foreground`

### warning [#warning]

Warning actions and emphasis for warning buttons, badges, alerts, status, etc.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-warning" /></span> `--warning`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-warning-foreground" /></span> `--warning-foreground`

### border [#border]

Default borders and separators on cards, menus, tables, separators, and layout dividers.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-border" /></span> `--border`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-border-foreground" /></span> `--border-foreground`

### input [#input]

Form control borders and input surface treatment on Input, Textarea, Select, and outline-style controls.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-input" /></span> `--input`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-input-foreground" /></span> `--input-foreground`

### ring [#ring]

Focus rings and outlines on buttons, inputs, checkboxes, menus, and other focusable controls. It follows the primary color.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-ring" /></span> `--ring`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-ring-foreground" /></span> `--ring-foreground`

### sidebar [#sidebar]

The base sidebar surface and default sidebar text on the Sidebar container and its default content.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-sidebar" /></span> `--sidebar`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-sidebar-foreground" /></span> `--sidebar-foreground`

### sidebar-primary [#sidebar-primary]

High-emphasis actions inside the sidebar for active items, icon tiles, badges, and sidebar CTAs.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-sidebar-primary" /></span> `--sidebar-primary`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-sidebar-primary-foreground" /></span> `--sidebar-primary-foreground`

### sidebar-accent [#sidebar-accent]

Hover and selected states inside the sidebar for menu hover states, open items, and interactive rows.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-sidebar-accent" /></span> `--sidebar-accent`
* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-sidebar-accent-foreground" /></span> `--sidebar-accent-foreground`

### sidebar-border [#sidebar-border]

Sidebar-specific borders and separators on sidebar headers, groups, and internal dividers.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-sidebar-border" /></span> `--sidebar-border`

### sidebar-ring [#sidebar-ring]

Sidebar-specific focus rings on focused controls inside the sidebar. It follows the primary color.

* <span className="inline-flex gap-1 mr-2 align-middle"><span className="inline-block size-8 rounded border border-border bg-sidebar-ring" /></span> `--sidebar-ring`

### radius [#radius]

The base corner radius scale for cards, inputs, buttons, popovers, and the derived `radius-*` tokens.

Preset theme classes are documented in [Styling](/docs/styling).


# Components (/docs/components)





<ComponentsList />


# Forms (/docs/forms)





## Picking a form library [#picking-a-form-library]

<FormsList />

For detailed guides with examples, validation, and field-type-specific patterns, see the linked pages above.

## Field Context [#field-context]

Form components automatically integrate with `Field` through context. When nested inside a `Field`, they inherit `disabled`, `invalid`, `required`, and `readOnly` states automatically.

Also `htmlFor` and `id` are automatically handled by the `Field` component. Never use them directly.

```tsx
import { Field } from "@/registry/react/components/field"
import { NumberInput } from "@/registry/react/components/number-input"

const Demo = () => (
  <Field disabled>
    <NumberInput>
      <NumberInputGroup>
        <NumberInputInput />
        <NumberInputIncrement />
        <NumberInputDecrement />
      </NumberInputGroup>
    </NumberInput>
  </Field>
)
```

## Input states [#input-states]

### Invalid [#invalid]

Pass the `invalid` prop to the `Field` component.

The `FieldError` is only visible when the `invalid` prop is `true`.

```tsx
import {
  Field,
  FieldLabel,
  FieldError,
} from "@/registry/react/components/field"
import { Input } from "@/registry/react/components/input"

const Demo = () => (
  <form>
    <Field invalid>
      <FieldLabel>Username</FieldLabel>
      <Input placeholder="Enter your username" />
      <FieldError>Username is required.</FieldError>
    </Field>
  </form>
)
```

### Required [#required]

Pass the `required` prop to the `Field` component.

Optionally, you can use the `FieldRequiredIndicator` to indicate that the field is required.

```tsx
import {
  Field,
  FieldLabel,
  FieldRequiredIndicator,
  FieldError,
} from "@/registry/react/components/field"
import { Input } from "@/registry/react/components/input"

export const Demo = () => (
  <form>
    <Field required>
      <FieldLabel>
        Username
        <FieldRequiredIndicator />
      </FieldLabel>
      <Input placeholder="Enter your username" />
      <FieldError>Username is required.</FieldError>
    </Field>
  </form>
)
```


# Introduction (/docs)



Built on top of [Ark UI](https://ark-ui.com) and [shadcn](https://ui.shadcn.com), it includes sensible defaults for styling, variants, and structure, so you can drop components into a project without starting from scratch. It’s not a black-box framework; you own the code, tweak what you need, and build on top of something that’s already thought through.

The name blends the two projects it’s built on: **sh** from shadcn and **ark** from Ark UI. **Shark**.

## Motivation [#motivation]

[Ark UI](https://ark-ui.com) offers a broad set of headless components and serves as a direct alternative to [Radix Primitives](https://radix-ui.com/primitives) and [Base UI](https://base-ui.com). It gives you accessible primitives and state management, but it leaves styling and layout entirely to you. **shadcn**, on the other hand, ships copy-paste components that look great. The gap is that Ark’s docs don’t show how to pair its primitives with Tailwind, or how to turn them into a reusable design system you can install, theme, and extend.

## How it works [#how-it-works]

Instead of only installing a package from npm and importing opaque pieces, you keep source in your repository and change it with your app. That sidesteps the usual spiral of wrappers, style overrides, and mismatched APIs when defaults are not enough.

This approach, where you keep and own the source code, means:

* **Full transparency:** You see exactly how each component is built, with no hidden layers between you and the implementation.
* **Easy customization:** Adjust any part of a component to match your design and functionality; you edit the source instead of working around a package API.
* **AI-friendly workflows:** Because the code lives in your repo, LLMs and teammates can read, reason about, and help improve components without reverse-engineering a library.

## AI Ready [#ai-ready]

The library is designed so **people and AI tools** can rely on it equally. Components are written to stay clear, readable, and predictable so assistants can understand structure, reason about changes, and modify files with less guesswork.

Because the source sits in your repository with **inspectable implementations** and **consistent patterns** from component to component, models get the context they need to read your UI layer end to end. An assistant can learn how your pieces work, propose refactors or small fixes, or generate new components that match your existing tokens, layout, and conventions.


# Installation (/docs/installation)





## Prerequisites [#prerequisites]

Components require [Tailwind CSS v4](https://tailwindcss.com). Before you begin, make sure you have a project set up with Tailwind CSS installed.

## Adding components [#adding-components]

### CLI [#cli]

```bash
npx shadcn@latest add @shark/<component>
```

### Manual [#manual]

Copy component source from the component docs via the Manual tab.

### All at once [#all-at-once]

```bash
npx shadcn@latest add @shark/ui
```

## New Project Setup [#new-project-setup]

For new projects, you have the `CLI` and `Manual` setup.

### CLI [#cli-1]

```bash
npx shadcn@latest init @shark/style
```

### Manual [#manual-1]

<FrameworksList />

## Styling [#styling]

For theming and layout setup, see [Styling](/docs/styling).

## Color system [#color-system]

See [Colors](/docs/colors) for the full palette and variable reference.


# LLMs.txt (/docs/llms-txt)



Shark UI provides [LLMs.txt](https://llmstxt.org/) endpoints so AI coding assistants can fetch documentation directly by URL.

## Available Files [#available-files]

**Core documentation:**

* [/llms.txt](/llms.txt) — Quick reference index for documentation
* [/llms-full.txt](/llms-full.txt) — Complete Shark UI documentation

**For limited context windows:**

* [/llms-components.txt](/llms-components.txt) — Component documentation only
* [/llms-patterns.txt](/llms-patterns.txt) — Common patterns and recipes

**All platforms:**

* [/llms.txt](/llms.txt) — Quick reference index
* [/llms-full.txt](/llms-full.txt) — Complete documentation
* [/llms-components.txt](/llms-components.txt) — All component documentation
* [/llms-patterns.txt](/llms-patterns.txt) — All patterns and recipes

## Integration [#integration]

**Claude Code:** Reference the docs in your prompt or add to your project’s `.claude` file:

```bash
Use Shark UI documentation from https://shark.vini.one/llms.txt
```

**Cursor:** Use the `@Docs` feature:

```bash
@Docs https://shark.vini.one/llms-full.txt
```

[Learn more](https://docs.cursor.com/context/@-symbols/@-docs)

**Windsurf:** Add to your `.windsurfrules` file:

```bash
#docs https://shark.vini.one/llms-full.txt
```

[Learn more](https://docs.codeium.com/windsurf/memories#memories-and-rules)

**Other AI tools:** Most assistants accept documentation URLs:

```bash
https://shark.vini.one/llms.txt
```

For component-specific documentation:

```bash
https://shark.vini.one/llms-components.txt
```

For patterns and best practices:

```bash
https://shark.vini.one/llms-patterns.txt
```

## Contributing [#contributing]

Spotted an issue with AI-generated code? Contributions to improve the LLMs.txt output are welcome on [GitHub](https://github.com/sharkui-inc/shark-ui).


# RTL (/docs/rtl)





<RTLExample />

## Setup [#setup]

Wrap your app with `LocaleProvider` and pass an RTL locale. Use this when you know the user’s language ahead of time or when the app switches locale dynamically.

```tsx showLineNumbers {4,6}
import { LocaleProvider } from "@/components/ui/locale";

export const App = () => (
  <LocaleProvider locale="ar-BH">
    {/* Your app */}
  </LocaleProvider>
);
```

Common RTL locales include `ar-BH`, `ar-SA`, `he-IL`, and `fa-IR`.

> **Note:** If no `LocaleProvider` is set up, the default locale is `en-US` and the direction stays `ltr`.

## Applying Direction [#applying-direction]

Read the current `dir` from `useLocale` and pass it to your root element—usually `<html>`—so the layout renders correctly and child components inherit the right text direction.

```tsx
import { LocaleProvider, useLocale } from "@/components/ui/locale";

const AppContent = () => {
  const { locale, dir } = useLocale();

  return (
    <html dir={dir} lang={locale}>
      {/* Your app content */}
    </html>
  );
};
```

## How it works [#how-it-works]

Shark UI components rely on logical CSS properties wherever possible. That means spacing and layout use `ms-*`, `me-*`, `ps-*`, `pe-*`, and `start-*` / `end-*` instead of physical ones like `ml-*`, `mr-*`, `left-*`, or `right-*`. When you flip `dir` to `rtl`, the layout adapts automatically because those utilities follow the text direction.

Setting `dir={dir}` on the root ensures that direction propagates down. Ark UI’s overlays, tooltips, and menus respect the document direction, so they position themselves correctly whether the user reads left-to-right or right-to-left.

## Animations [#animations]

Animations should follow the reading direction. Physical utilities like `slide-in-from-right` will slide the wrong way in RTL. Use logical alternatives so motion stays consistent:

* `slide-in-from-end` / `slide-out-to-end` instead of `slide-in-from-right` / `slide-out-to-right`
* `slide-in-from-start` / `slide-out-to-start` instead of `slide-in-from-left` / `slide-out-to-left`

***

For the full API reference, see the [Ark UI documentation](https://ark-ui.com/docs/utilities/locale).


# Skills (/docs/skills)



This skill covers Shark UI components, patterns, and styling. Your assistant uses it to implement those pieces correctly in your project.

You can ask for something concrete:

* *“Add a settings dialog with a form and save/cancel buttons.”*
* *“Add a combobox with search filtering.”*
* *“Migrate this shadcn dropdown to Shark’s Menu.”*
* *“Add a Select with grouped options and a placeholder.”*

## Installation [#installation]

```bash
npx skills add sharkui-inc/shark-ui
```

The public directory and leaderboard live at [skills.sh](https://skills.sh).

## What you get [#what-you-get]

The layout matches other mature UI skills: a compact entry file and deeper material you load only when the task needs it.

### Component knowledge [#component-knowledge]

Your assistant gets a map of the registry: what to import, how parts nest, and where the sharp edges are. Overlays (**Dialog** vs **Sheet**), menus (**Menu** vs **Context Menu**), list controls (**Select** vs **Combobox** with collections and filters), **Field**-driven forms, and **Sidebar** shells each have a short guide in the skill pack. That material stays aligned with the published component list in this project and the MDX on this site, so “what the skill says” and “what the docs say” stay in sync.

### Styling conventions [#styling-conventions]

Tailwind CSS v4, semantic tokens, and the small habits that keep Shark visually consistent, plus the editorial rules we keep for examples and previews (thumbs, field widths, chart tooltips, sidebar preview framing, and similar detail).

### Migration patterns [#migration-patterns]

When someone pastes radix, base-ui, or shadcn-shaped code, the skill nudges the rewrite toward **Shark UI**: collection objects for list primitives, and the chart or sidebar patterns we actually ship, not a generic “swap the import path” pass.

### CLI and registry [#cli-and-registry]

The same workflow this site documents for adding components (shadcn-style CLI and the public registry JSON hosted here). The skill reminds agents to follow each component’s installation section, dependency list, and registry entry.

### Registry examples [#registry-examples]

Every serious answer should look at the shipped examples that sit beside each component in source. Those snippets are the library’s own compositions; matching them keeps generated UI aligned with how Shark is maintained, not a one-line stub from a model’s training cut-off.

## How it works [#how-it-works]

1. **Activation:** After install, your agent discovers the skill the same way it discovers other Agent Skills.
2. **Progressive depth:** The **SKILL.md** file links into the registry index, shared rule files, and per-component notes only when the prompt touches that surface.
3. **Pattern enforcement:** The assistant follows Shark composition, combobox collection and filtering, chart tooltip wiring where applicable, sidebar preview layout, and the import conventions.
4. **Examples before invention:** The workflow tells the model to read the MDX for the component and the matching example snippets.

## Supported agents [#supported-agents]

Any editor or CLI that implements the [Agent Skills](https://agentskills.io) layout can consume this bundle: Claude Code, Cursor, Codex, Cline, Windsurf, GitHub Copilot, and the rest of the list on [skills.sh](https://skills.sh).

## In the repository [#in-the-repository]

The skill is versioned in the same open-source project as Shark UI. If you want to read or change it, open the project on [GitHub](https://github.com/sharkui-inc/shark-ui/tree/main/skills/shark-ui).


# Styling (/docs/styling)



## Overview [#overview]

Shark UI’s styling system is built for clarity and consistent theming. It follows [shadcn/ui theme tokens](https://ui.shadcn.com/docs/theming#theme-tokens) and adds three extra tokens: `success`, `warning`, and `info` to cover status states.

## CSS Configuration [#css-configuration]

See [Installation](/docs/installation#new-project-setup) for installing with CLI. To add the theme yourself, paste the following into `globals.css`:

<CodeCollapsibleWrapper>
  ```css title="globals.css"
  @theme inline {
    --color-background: var(--background);
    --color-foreground: var(--foreground);
    --color-card: var(--card);
    --color-card-foreground: var(--card-foreground);
    --color-popover: var(--popover);
    --color-popover-foreground: var(--popover-foreground);
    --color-primary: var(--primary);
    --color-primary-foreground: var(--primary-foreground);
    --color-secondary: var(--secondary);
    --color-secondary-foreground: var(--secondary-foreground);
    --color-muted: var(--muted);
    --color-muted-foreground: var(--muted-foreground);
    --color-accent: var(--accent);
    --color-accent-foreground: var(--accent-foreground);
    --color-destructive: var(--destructive);
    --color-destructive-foreground: var(--destructive-foreground);
    --color-info: var(--info);
    --color-info-foreground: var(--info-foreground);
    --color-success: var(--success);
    --color-success-foreground: var(--success-foreground);
    --color-warning: var(--warning);
    --color-warning-foreground: var(--warning-foreground);
    --color-border: var(--border);
    --color-input: var(--input);
    --color-ring: var(--ring);
    --color-sidebar: var(--sidebar);
    --color-sidebar-foreground: var(--sidebar-foreground);
    --color-sidebar-primary: var(--sidebar-primary);
    --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
    --color-sidebar-accent: var(--sidebar-accent);
    --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
    --color-sidebar-border: var(--sidebar-border);
    --color-sidebar-ring: var(--sidebar-ring);
    --color-chart-1: var(--chart-1);
    --color-chart-2: var(--chart-2);
    --color-chart-3: var(--chart-3);
    --color-chart-4: var(--chart-4);
    --color-chart-5: var(--chart-5);
    --radius-xs: calc(var(--radius) * 0.25);
    --radius-sm: calc(var(--radius) * 0.5);
    --radius-md: calc(var(--radius) * 0.75);
    --radius-lg: calc(var(--radius) * 1);
    --radius-xl: calc(var(--radius) * 1.5);
    --radius-2xl: calc(var(--radius) * 2);
    --radius-3xl: calc(var(--radius) * 3);
    --radius-4xl: calc(var(--radius) * 4);
  }

  :root {
    --radius: 0.5rem;
    --background: var(--color-neutral-50);
    --foreground: var(--color-neutral-800);
    --card: var(--color-neutral-50);
    --card-foreground: var(--color-neutral-800);
    --popover: var(--color-neutral-50);
    --popover-foreground: var(--color-neutral-800);
    --primary: var(--color-neutral-800);
    --primary-foreground: var(--color-neutral-50);
    --secondary: color-mix(
      in srgb,
      var(--color-neutral-950) 6%,
      var(--background)
    );
    --secondary-foreground: var(--color-neutral-800);
    --muted: color-mix(in srgb, var(--color-neutral-950) 6%, var(--background));
    --muted-foreground: color-mix(
      in srgb,
      var(--color-neutral-500) 80%,
      var(--color-neutral-950)
    );
    --accent: color-mix(in srgb, var(--color-neutral-950) 6%, var(--background));
    --accent-foreground: var(--color-neutral-800);
    --destructive: var(--color-red-500);
    --destructive-foreground: var(--color-red-700);
    --info: var(--color-blue-500);
    --info-foreground: var(--color-blue-700);
    --success: var(--color-emerald-500);
    --success-foreground: var(--color-emerald-700);
    --warning: var(--color-amber-500);
    --warning-foreground: var(--color-amber-700);
    --border: color-mix(in srgb, var(--color-neutral-950) 12%, var(--background));
    --input: color-mix(in srgb, var(--color-neutral-950) 13%, var(--background));
    --ring: var(--color-neutral-400);
    --sidebar: var(--color-neutral-50);
    --sidebar-foreground: color-mix(
      in srgb,
      var(--color-neutral-800) 64%,
      var(--sidebar)
    );
    --sidebar-primary: var(--color-neutral-800);
    --sidebar-primary-foreground: var(--color-neutral-50);
    --sidebar-accent: color-mix(
      in srgb,
      var(--color-neutral-950) 6%,
      var(--sidebar)
    );
    --sidebar-accent-foreground: var(--color-neutral-800);
    --sidebar-border: color-mix(
      in srgb,
      var(--color-neutral-950) 11%,
      var(--sidebar)
    );
    --sidebar-ring: var(--color-neutral-400);
    --chart-1: var(--color-orange-600);
    --chart-2: var(--color-teal-600);
    --chart-3: var(--color-cyan-900);
    --chart-4: var(--color-amber-400);
    --chart-5: var(--color-amber-500);
  }

  .dark {
    --background: var(--color-neutral-950);
    --foreground: var(--color-neutral-100);
    --card: color-mix(in srgb, var(--background) 98%, var(--color-neutral-50));
    --card-foreground: var(--color-neutral-100);
    --popover: color-mix(
      in srgb,
      var(--background) 96%,
      var(--color-neutral-50)
    );
    --popover-foreground: var(--color-neutral-100);
    --primary: var(--color-neutral-100);
    --primary-foreground: var(--color-neutral-800);
    --secondary: color-mix(in srgb, var(--color-white) 8%, var(--background));
    --secondary-foreground: var(--color-neutral-100);
    --muted: color-mix(in srgb, var(--color-neutral-50) 8%, var(--background));
    --muted-foreground: color-mix(
      in srgb,
      var(--color-neutral-500) 70%,
      var(--color-neutral-50)
    );
    --accent: color-mix(in srgb, var(--color-neutral-50) 8%, var(--background));
    --accent-foreground: var(--color-neutral-100);
    --destructive: color-mix(
      in srgb,
      var(--color-red-600) 90%,
      var(--color-neutral-50)
    );
    --destructive-foreground: var(--color-red-400);
    --info: var(--color-blue-500);
    --info-foreground: var(--color-blue-400);
    --success: var(--color-emerald-500);
    --success-foreground: var(--color-emerald-400);
    --warning: var(--color-amber-500);
    --warning-foreground: var(--color-amber-400);
    --border: color-mix(in srgb, var(--color-neutral-50) 12%, var(--background));
    --input: color-mix(in srgb, var(--color-neutral-50) 13%, var(--background));
    --ring: var(--color-neutral-500);
    --sidebar: color-mix(
      in srgb,
      var(--color-neutral-950) 97%,
      var(--color-neutral-50)
    );
    --sidebar-foreground: color-mix(
      in srgb,
      var(--color-neutral-100) 64%,
      var(--sidebar)
    );
    --sidebar-primary: var(--color-neutral-100);
    --sidebar-primary-foreground: var(--color-neutral-800);
    --sidebar-accent: color-mix(
      in srgb,
      var(--color-neutral-50) 8%,
      var(--sidebar)
    );
    --sidebar-accent-foreground: var(--color-neutral-100);
    --sidebar-border: color-mix(
      in srgb,
      var(--color-neutral-50) 11%,
      var(--sidebar)
    );
    --sidebar-ring: var(--color-neutral-400);
    --chart-1: var(--color-blue-700);
    --chart-2: var(--color-emerald-500);
    --chart-3: var(--color-amber-500);
    --chart-4: var(--color-purple-500);
    --chart-5: var(--color-rose-500);
  }
  ```
</CodeCollapsibleWrapper>

{/* TODO: work on font-heading
  ## Font Variables

  The theme preset defines `--font-sans` with system fallbacks. To use custom typefaces, set this variable in your layout via `next/font` or `@fontsource-variable`:

  ```tsx title="app/layout.tsx"
  import { Inter } from "next/font/google";

  const fontSans = Inter({ variable: "--font-sans", subsets: ["latin"] });

  export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body
        className={fontSans.variable}
      >
        {children}
      </body>
    </html>
  );
  }
  ``` */}

## Token convention [#token-convention]

Each color has two tokens: the base name is the **fill*&#x2A;. The same name with &#x2A;*`-foreground`** is the **text** and **icon** color meant to sit on that fill. Use both together on every new surface so content stays readable.

```tsx
<div className="bg-primary text-primary-foreground" />
```

## Adding new tokens [#adding-new-tokens]

New variables must be wired through &#x2A;*`@theme inline`** as `--color-*` entries. See [Tailwind CSS](https://tailwindcss.com/docs/theme)

```css title="globals.css"
@theme inline {
  --color-brand: var(--brand);
  --color-brand-foreground: var(--brand-foreground);
}

:root {
  --brand: oklch(0.55 0.18 250);
  --brand-foreground: oklch(0.99 0 0);
}
```

## Customizing colors [#customizing-colors]

Override variables on `:root` and `.dark`. Always update foreground when you change a fill.

```css title="globals.css"
:root {
  --primary: oklch(76.8% 0.233 130.85);
  --primary-foreground: oklch(98.6% 0.031 120.757);
}

.dark {
  --primary: oklch(53.2% 0.157 131.589);
  --primary-foreground: oklch(96.7% 0.067 122.328);
}
```

## Radius Scale [#radius-scale]

`--radius` is the base radius token for your theme.

We derive a small radius scale from it so components can use consistent corner sizes while still sharing a single source of truth.

```css title="app/globals.css" showLineNumbers
@theme inline {
  --radius-xs: calc(var(--radius) * 0.25);
  --radius-sm: calc(var(--radius) * 0.5);
  --radius-md: calc(var(--radius) * 0.75);
  --radius-lg: calc(var(--radius) * 1);
  --radius-xl: calc(var(--radius) * 1.5);
  --radius-2xl: calc(var(--radius) * 2);
  --radius-3xl: calc(var(--radius) * 3);
  --radius-4xl: calc(var(--radius) * 4);
}

:root {
  --radius: 0.5rem;
}
```

This means:

* `radius-lg` is the base value.
* Smaller radius scale down from `--radius`.
* Larger radius scale up from `--radius`.
* Changing `--radius` updates the entire radius scale.

## Color system [#color-system]

See [Colors](/docs/colors) for the full token reference, and naming rules.


# January 2026 - Beta 1 (/docs/changelog/26-01-first-beta)



Beta 1 marks the first public release of Shark UI. The goal was to build a set of components on [Ark UI](https://ark-ui.com) styled with [Tailwind CSS](https://tailwindcss.com), so you can add accessible primitives to a project without wiring up styles from scratch.

## Components [#components]

Roughly 80+ components are available, grouped into several categories:

* **UI primitives**: Accordion, Alert, Avatar, Badge, Button, Card, Separator, Skeleton, Tabs
* **Overlays and dialogs**: Dialog, Menu, Popover, Sheet, Tooltip, Hover Card, Context Menu
* **Forms and inputs**: Input, Textarea, Checkbox, Radio Group, Select, Native Select, Field, Combobox, Input OTP, File Upload, Editable
* **Layout and navigation**: Sidebar, Scroll Area, Resizable, Pagination, Breadcrumb, Bottom Navigation
* **Feedback and display**: Progress, Slider, Rating Group, Toggle, Toggle Group, Steps, Carousel

Components are copy-paste: they land in your project, and you own the code. Tailwind and Ark UI are the only runtime dependencies.

## Theme editor [#theme-editor]

The theme editor lets you tweak colors and copy the resulting CSS variables into your project. Themes follow the shadcn color convention, with extra variables for success, warning, info, and destructive states.

## Limitations [#limitations]

This is a beta. Some components may change before a stable release. If you run into issues, open an issue on [GitHub](https://github.com/sharkui-inc/shark-ui).


# March 2026 - Release Candidate (/docs/changelog/26-03-rc)



This release candidate builds on Beta 1 with new components, utilities, theme editor enhancements, and improved documentation. The component registry has been restructured with thumbs and consistent example naming.

## New Components [#new-components]

* **Announcement** — Banner-style component for promotions and notices
* **Calendar** — Full calendar with month/year navigation and range selection
* **Color Picker** — Color selection with swatches and input fields
* **Date Picker** — Date input with calendar popover and presets
* **Drawer** — Slide-out panel for mobile-first layouts
* **Image Cropper** — Crop images with zoom, aspect ratio, and constraints
* **Prose** — Typography styles for markdown and long-form content
* **Signature Pad** — Canvas-based signature capture
* **Skip Nav** — Accessibility link to skip to main content
* **Timer** — Countdown, interval, and Pomodoro timers

## New Utilities [#new-utilities]

* **Client Only** — Render components only on the client
* **Format** — Date, number, and relative time formatting
* **Show** — Conditional rendering with animation support
* **Download Trigger** — Programmatic file downloads
* **Swap** — Toggle between two states with animation
* **Presence** — Mount/unmount with enter/exit animations
* **JSON Tree View** — Expandable JSON display
* **Highlight** — Syntax highlighting for code blocks

## Component Updates [#component-updates]

Registry examples and thumbs were standardized across components:

* **Button** — Variants, sizes, and icon support
* **Card** — Composition and theming
* **Combobox** — Multi-select and controlled state
* **Dialog** — Sizes and compositions
* **Field** — Required fields and validation
* **Floating Panel** — Positions and resize behavior
* **Input Group** — Button integration and addons
* **Menu** — Nested menus and keyboard navigation
* **Number Input** — Stepper and format options
* **Pagination** — Sizes and variants
* **Select** — Multi-select and custom items
* **Textarea** — Autoresize and validation
* **Toast** — Placement, types, and promises
* **Toggle** — Sizes, outline, and icon variants
* **Tooltip** — Positioning and keyboard support
* **Tour** — Step types, progress, and async steps

## Theme Editor [#theme-editor]

* Updated color variable system and theme presets
* Support for success, warning, info, and destructive states
* Prose typography styles for content blocks

## Home Page [#home-page]

* Redesigned hero with Announcement component
* Component examples (Input OTP, forms, calendar, charts, and more)
* Framework support badges (React, Solid, Vue, Svelte)
* Theme cards for activity, chat, and sharing examples

## Documentation [#documentation]

* **Forms** — New forms section with React Hook Form and TanStack Form guides
* **RTL** — Right-to-left layout support
* Component docs updated with API references and examples
* New installation guides for various frameworks

## Infrastructure [#infrastructure]

* Open Graph image generation for docs and changelog
* RSS feed and sitemap generation
* LLMs.txt route for AI crawlers

## Dependencies [#dependencies]

* Package updates for Next.js, React, Ark UI, and dev tooling


# May 2026 - Post-RC updates (/docs/changelog/26-05-post-rc)



This update follows the March release candidate with ecosystem listing, a new Hitbox utility, expanded hooks and agent documentation, site improvements, and many fixes across theming and components.

## Registry & ecosystem [#registry--ecosystem]

* **shadcn registry** — Shark UI is wired into the broader shadcn registry configuration via `components.json`
* **Registry build** — Manifest and `public/r/*.json` metadata refreshed; registry build script updated for maintainers

## New utility [#new-utility]

* **Hitbox** — Enlarge tap and click targets without changing layout; includes docs, registry examples, and dedicated styles

## Hooks & CLI-facing docs [#hooks--cli-facing-docs]

* **use-is-mobile** — Documented hook for responsive behavior
* **style**, **ui**, **utils** — Registry items exposed for CLI installs alongside other meta updates

## Site & product [#site--product]

* **Blocks** — Early `/blocks` route scaffold for the blocks experience
* **Analytics** — Site analytics integration
* **Funding** — Ko-fi support link in project metadata
* **Agent skill** — Shark UI skill for Cursor and expanded primitive references for contributors and coding agents

## Documentation & layout [#documentation--layout]

* **Installation & components** — Dedicated overview pages for installation and the component index (`ComponentsList`), with framework guides remaining under Installation
* **Docs shell** — Fixes for table of contents when headings are sparse, component doc routing, CLI copy snippets, and content replacement behavior
* **Layout** — Global scrollbar and overflow refinements on the docs body

## Components & theming [#components--theming]

* **Theme** — Switcher reliability and reduced first-paint flicker; border and input CSS variables; background token alignment
* **Dialog** — RTL layout fix
* **Table** — Spacing and header text treatment
* **CodeBlock** / **Highlight** — Standardized prop for line numbers
* **Badge** — Improved touch behavior for coarse pointers
* **Combobox** — Follow-up fixes and examples after the combobox workstream
* **Announcement** — Updates from community PRs
* **Drawer**, **Toast**, **Sidebar**, **Timer**, **Prose** — Props, examples, and styling tweaks
* **data-slot** — Consistency fix for slot-based styling hooks

## Dependencies & infrastructure [#dependencies--infrastructure]

* Dependency updates and small component refactors
* CI workflow adjustments for contributor runs


# Changelog (/docs/changelog)



Releases are listed by date, newest first. Each entry describes what changed—components added or updated, breaking changes, and fixes. For release tags and diffs, check the [Shark UI repository](https://github.com/sharkui-inc/shark-ui) on GitHub.


# Accordion (/docs/components/accordion)



<ComponentPreview componentName="accordion" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/accordion
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Add the following animations to your 

        `globals.css`

        .
      </Step>

      ```css title="globals.css" showLineNumbers
      @theme inline {
        --animate-slide-up: slideUp 0.2s ease-out;
        --animate-slide-down: slideDown 0.2s ease-out;

        @keyframes slideUp {
          from { height: var(--height); }
          to { height: 0; }
        }
        @keyframes slideDown {
          from { height: 0; }
          to { height: var(--height); }
        }
      }
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/accordion.tsx" src="/accordion.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Accordion
└── AccordionItem
    ├── AccordionTrigger
    └── AccordionContent
```

## Usage [#usage]

```tsx
import { 
  Accordion, 
  AccordionItem, 
  AccordionTrigger, 
  AccordionContent 
} from "@/components/ui/accordion";
```

```tsx
<Accordion>
  <AccordionItem value="item-1">
    <AccordionTrigger>
      Is it accessible?
    </AccordionTrigger>
    <AccordionContent>
      Yes. It adheres to the WAI-ARIA design pattern.
    </AccordionContent>
  </AccordionItem>
</Accordion>
```

## Controlled [#controlled]

Use the `value` and `onValueChange` props to control the accordion state programmatically.

<ComponentPreview componentName="accordion" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

<ComponentPreview componentName="accordion" fileName="example-disabled" />

## Examples [#examples]

### Non-collapsible [#non-collapsible]

Set the `collapsible` prop to `false` to disable the collapsible behavior.

<ComponentPreview componentName="accordion" fileName="example-non-collapsible" />

### Multiple [#multiple]

Use the `multiple` prop to allow multiple items to be open simultaneously.

<ComponentPreview componentName="accordion" fileName="example-multiple" />

### Card [#card]

Wrap the `Accordion` in a `Card` component.

<ComponentPreview componentName="accordion" fileName="example-card" />

## API Reference [#api-reference]

### Accordion [#accordion]

Root component.

| Prop            | Type                 | Default |
| --------------- | -------------------- | ------- |
| `value`         | `string[]`           | `-`     |
| `defaultValue`  | `string[]`           | `-`     |
| `collapsible`   | `boolean`            | `true`  |
| `multiple`      | `boolean`            | `false` |
| `onValueChange` | `ValueChangeDetails` | `-`     |
| `className`     | `string`             | `-`     |
| `asChild`       | `boolean`            | `false` |

### AccordionItem [#accordionitem]

Single accordion item.

| Prop        | Type      | Default      |
| ----------- | --------- | ------------ |
| `value`     | `string`  | **required** |
| `disabled`  | `boolean` | `false`      |
| `className` | `string`  | `-`          |

### AccordionTrigger [#accordiontrigger]

Toggles the item open/closed on click.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `disabled`  | `boolean` | `false` |
| `className` | `string`  | `-`     |

### AccordionContent [#accordioncontent]

Holds the collapsible content for the item.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/accordion#api-reference).


# Action Bar (/docs/components/action-bar)



<ComponentPreview componentName="action-bar" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/action-bar
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Badge](/docs/components/badge)

        , and 

        [Separator](/docs/components/separator)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/action-bar.tsx" src="/action-bar.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
ActionBar
├── ActionBarTrigger
└── ActionBarContent
    ├── ActionBarValue
    ├── ActionBarSeparator
    ├── ActionBarBody
    │   ├── Button
    ├── ActionBarSeparator
    └── ActionBarClose
```

## Usage [#usage]

```tsx
import {
  ArchiveIcon,
  DownloadIcon,
  PencilIcon,
  Trash2Icon,
  XIcon,
} from "lucide-react";
import {
  ActionBar,
  ActionBarBody,
  ActionBarClose,
  ActionBarContent,
  ActionBarSeparator,
  ActionBarTrigger,
  ActionBarValue,
} from "@/components/ui/action-bar";
import { Button } from "@/components/ui/button";
```

```tsx
<ActionBar>
  <ActionBarTrigger asChild>
    <Button variant="outline">Open</Button>
  </ActionBarTrigger>
  <ActionBarContent>
    <ActionBarValue count={3} />
    <ActionBarSeparator />
    <ActionBarBody>
      <Button variant="ghost">
        <PencilIcon />
        <span className="max-sm:sr-only">Edit</span>
      </Button>
      <ActionBarSeparator />
      <Button variant="destructive">
        <Trash2Icon />
        <span className="max-sm:sr-only">Delete</span>
      </Button>
    </ActionBarBody>
    <ActionBarSeparator />
    <ActionBarClose asChild>
      <Button size="icon-md" variant="ghost">
        <XIcon />
      </Button>
    </ActionBarClose>
  </ActionBarContent>
</ActionBar>
```

## Controlled [#controlled]

<ComponentPreview componentName="action-bar" fileName="example-controlled" />

## Examples [#examples]

### Positioning [#positioning]

Use the `positioning.placement` prop to position the action bar.

<ComponentPreview componentName="action-bar" fileName="example-positioning" />

### Gutter [#gutter]

Use `positioning.gutter` to control the distance from the bottom edge.

<ComponentPreview componentName="action-bar" fileName="example-gutter" />

### Close Trigger [#close-trigger]

<ComponentPreview componentName="action-bar" fileName="example-close-trigger" />

### With Dialog [#with-dialog]

<ComponentPreview componentName="action-bar" fileName="example-dialog" />

### With Menu [#with-menu]

<ComponentPreview componentName="action-bar" fileName="example-menu" />

### Table [#table]

<ComponentPreview componentName="action-bar" fileName="example-table" />

### Custom Spacing [#custom-spacing]

The `[--space:--spacing("value")]` on `ActionBarContent` controls the internal spacing.

Default spacing is `--spacing(2)`.

<ComponentPreview componentName="action-bar" fileName="example-custom-spacing" />

> You can use breakpoint utilities to change the internal spacing at different screen sizes.

```css
md:[--space:--spacing(6)] lg:[--space:--spacing(8)]
```

## API Reference [#api-reference]

### ActionBar [#actionbar]

Root component. Provides open state and positioning to descendants.

| Prop            | Type                      | Default                                   |
| --------------- | ------------------------- | ----------------------------------------- |
| `open`          | `boolean`                 | -                                         |
| `defaultOpen`   | `boolean`                 | `false`                                   |
| `positioning`   | `ActionBarPositioning`    | `{ placement: "bottom", gutter: "16px" }` |
| `lazyMount`     | `boolean`                 | `true`                                    |
| `unmountOnExit` | `boolean`                 | `true`                                    |
| `closeOnEscape` | `boolean`                 | `true`                                    |
| `onOpenChange`  | `(open: boolean) => void` | -                                         |

### ActionBarContent [#actionbarcontent]

Root component.

| Prop         | Type      | Default |
| ------------ | --------- | ------- |
| `className`  | `string`  | -       |
| `aria-label` | `string`  | -       |
| `asChild`    | `boolean` | -       |

| CSS variable | Default        |
| ------------ | -------------- |
| `--space`    | `--spacing(2)` |

### ActionBarTrigger [#actionbartrigger]

Button that opens the action bar.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### ActionBarValue [#actionbarvalue]

Displays the selection count.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `count`     | `number`  | -       |
| `label`     | `string`  | -       |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### ActionBarSeparator [#actionbarseparator]

Vertical rule. Renders a [Separator](/docs/components/separator).

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### ActionBarBody [#actionbarbody]

Flex row for primary actions.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### ActionBarClose [#actionbarclose]

Closes the action bar.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |


# Alert Dialog (/docs/components/alert-dialog)



<Alert>
  <InfoIcon />

  <AlertDescription>
    Alert Dialog is built on top of the [Dialog](/docs/components/dialog) component. Check it out for more examples.
  </AlertDescription>
</Alert>

<ComponentPreview componentName="alert-dialog" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/alert-dialog
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

         and 

        [Dialog](/docs/components/dialog)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/alert-dialog.tsx" src="/alert-dialog.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
AlertDialog
├── AlertDialogTrigger
└── AlertDialogContent
    ├── AlertDialogHeader
    │   ├── AlertDialogTitle
    │   └── AlertDialogDescription
    ├── AlertDialogBody
    ├── AlertDialogFooter
    │   ├── AlertDialogCancel
    │   └── AlertDialogAction
    └── AlertDialogClose
```

## Usage [#usage]

```tsx
import { 
  AlertDialog, 
  AlertDialogTrigger, 
  AlertDialogContent, 
  AlertDialogHeader,
  AlertDialogTitle, 
  AlertDialogDescription, 
  AlertDialogBody,
  AlertDialogFooter,
  AlertDialogAction,
  AlertDialogCancel,
} from "@/components/ui/alert-dialog";
```

```tsx
<AlertDialog>
  <AlertDialogTrigger asChild>
    <Button variant="outline">Open</Button>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Allow accessory to connect?</AlertDialogTitle>
      <AlertDialogDescription>
        Do you want to allow the USB accessory to connect to this device?
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogBody />
    <AlertDialogFooter>
      <AlertDialogCancel>
        Don't allow
      </AlertDialogCancel>
      <AlertDialogClose asChild>
        <AlertDialogAction>Allow</AlertDialogAction>
      </AlertDialogClose>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

## Title & Description [#title--description]

`AlertDialogHeader` supports two usage patterns:

### Using props [#using-props]

Pass `title` and `description` props directly to `AlertDialogHeader`.

```tsx showLineNumbers
<AlertDialogHeader 
  title="Allow accessory to connect?" 
  description="Do you want to allow the USB accessory to connect to this device?"
>
  <AlertDialogAction />
</AlertDialogHeader>
```

> This approach does not require `AlertDialogTitle` or `AlertDialogDescription` components.

### Using components [#using-components]

Use `AlertDialogTitle` and `AlertDialogDescription` as children for more control.

```tsx showLineNumbers
<AlertDialogHeader>
  <AlertDialogTitle>Allow accessory to connect?</AlertDialogTitle>
  <AlertDialogDescription>
    Do you want to allow the USB accessory to connect to this device?
  </AlertDialogDescription>
  <AlertDialogAction />
</AlertDialogHeader>
```

## Examples [#examples]

### Destructive [#destructive]

<ComponentPreview componentName="alert-dialog" fileName="example-variant-destructive" />

## API Reference [#api-reference]

### AlertDialogAction [#alertdialogaction]

Primary action.

| Prop        | Type                         | Default     |
| ----------- | ---------------------------- | ----------- |
| `variant`   | `"default" \| "destructive"` | `"default"` |
| `className` | `string`                     | `-`         |
| `asChild`   | `boolean`                    | `false`     |

### AlertDialogCancel [#alertdialogcancel]

Cancel action.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

***

For a complete list of props, see the [Dialog API Reference](/docs/components/dialog#api-reference).


# Alert (/docs/components/alert)





<ComponentPreview componentName="alert" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/alert
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Import the following variables into your CSS file
      </Step>

      <CodeCollapsibleWrapper>
        ```css
        @theme inline {
          --color-destructive-foreground: var(--destructive-foreground);
          --color-info: var(--info);
          --color-info-foreground: var(--info-foreground);
          --color-success: var(--success);
          --color-success-foreground: var(--success-foreground);
          --color-warning: var(--warning);
          --color-warning-foreground: var(--warning-foreground);
        }

        :root {
          --destructive-foreground: var(--color-red-700);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-700);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-700);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-700);
        }

        .dark {
          --destructive-foreground: var(--color-red-400);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-400);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-400);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-400);
        }
        ```
      </CodeCollapsibleWrapper>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/alert.tsx" src="/alert.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Alert
├── Icon
├── AlertTitle
├── AlertDescription
└── AlertAction
```

## Usage [#usage]

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

```tsx
<Alert>
  <AlertTitle>Heads up!</AlertTitle>
  <AlertDescription>You can add icons to alerts.</AlertDescription>
  <AlertAction>
    <Button size="xs" variant="ghost">Dismiss</Button>
    <Button size="xs">Update</Button>
  </AlertAction>
</Alert>
```

## Variants [#variants]

### Default [#default]

<ComponentPreview componentName="alert" fileName="example-variant-default" />

### Info [#info]

<ComponentPreview componentName="alert" fileName="example-variant-info" />

### Warning [#warning]

<ComponentPreview componentName="alert" fileName="example-variant-warning" />

### Success [#success]

<ComponentPreview componentName="alert" fileName="example-variant-success" />

### Destructive [#destructive]

<ComponentPreview componentName="alert" fileName="example-variant-destructive" />

## Examples [#examples]

### With icon [#with-icon]

<ComponentPreview componentName="alert" fileName="example-with-icon" />

### With action [#with-action]

<ComponentPreview componentName="alert" fileName="example-with-action" />

### Custom color [#custom-color]

<ComponentPreview componentName="alert" fileName="example-custom-color" />

## API Reference [#api-reference]

### Alert [#alert]

Root component.

| Prop        | Type                                                             | Default     |
| ----------- | ---------------------------------------------------------------- | ----------- |
| `variant`   | `"default" \| "info" \| "warning" \| "success" \| "destructive"` | `"default"` |
| `className` | `string`                                                         | `-`         |
| `asChild`   | `boolean`                                                        | `false`     |

### AlertTitle [#alerttitle]

Title text.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### AlertDescription [#alertdescription]

Description text.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### AlertAction [#alertaction]

Container for action buttons. Automatically positioned to the right on larger screens.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |


# Announcement (/docs/components/announcement)



<ComponentPreview componentName="announcement" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/announcement
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/announcement.tsx" src="/announcement.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Announcement
├── Badge
└── AnnouncementTitle
```

## Usage [#usage]

```tsx
import {
  Announcement,
  AnnouncementTitle,
} from "@/components/ui/announcement";
```

```tsx
<Announcement>
  <Badge>
    <SparklesIcon />
  </Badge>
  <AnnouncementTitle>New feature added</AnnouncementTitle>
</Announcement>
```

## Variants [#variants]

### Info [#info]

<ComponentPreview componentName="announcement" fileName="example-variant-info" />

### Success [#success]

<ComponentPreview componentName="announcement" fileName="example-variant-success" />

### Warning [#warning]

<ComponentPreview componentName="announcement" fileName="example-variant-warning" />

### Destructive [#destructive]

<ComponentPreview componentName="announcement" fileName="example-variant-destructive" />

## Examples [#examples]

### With icon [#with-icon]

<ComponentPreview componentName="announcement" fileName="example-with-icon" />

### With link [#with-link]

The `asChild` prop renders a link with announcement styling.

<ComponentPreview componentName="announcement" fileName="example-with-link" />

### Without Badge [#without-badge]

The announcement supports a title-only layout without the badge component.

<ComponentPreview componentName="announcement" fileName="example-without-badge" />

## API Reference [#api-reference]

### Announcement [#announcement]

Root wrapper for announcement banners or notices.

| Prop        | Type                  | Default    |
| ----------- | --------------------- | ---------- |
| `role`      | `"status" \| "alert"` | `"status"` |
| `className` | `string`              | `-`        |
| `asChild`   | `boolean`             | `false`    |

### AnnouncementTitle [#announcementtitle]

Main title or message of the announcement.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |


# Aspect Ratio (/docs/components/aspect-ratio)



<ComponentPreview componentName="aspect-ratio" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/aspect-ratio
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/aspect-ratio.tsx" src="/aspect-ratio.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

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

```tsx
<AspectRatio>
  <img
    src="/image.jpg"
    alt="Description"
    className="object-cover size-full"
  />
</AspectRatio>
```

## Examples [#examples]

### Square [#square]

<ComponentPreview componentName="aspect-ratio" fileName="example-square" />

### Portrait [#portrait]

<ComponentPreview componentName="aspect-ratio" fileName="example-portrait" />

### Video [#video]

<ComponentPreview componentName="aspect-ratio" fileName="example-video" />

### Responsive [#responsive]

Use `[--ratio:*]` with breakpoints to change the ratio at different screen sizes.

<ComponentPreview componentName="aspect-ratio" fileName="example-responsive" />

> You can use breakpoint utilities to change the aspect ratio at different screen sizes.

```css
  md:[--ratio:16/9] lg:[--ratio:16/9]
```

## API Reference [#api-reference]

### AspectRatio [#aspectratio]

Root component.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

| Attribute | Description |
| --------- | ----------- |
| `--ratio` | `1`         |


# Autocomplete (/docs/components/autocomplete)



<ComponentPreview componentName="autocomplete" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/autocomplete
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Combobox](/docs/components/combobox)

        , and 

        [Separator](/docs/components/separator)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/autocomplete.tsx" src="/autocomplete.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Autocomplete
├── AutocompleteInput
└── AutocompleteContent
    ├── AutocompleteEmpty
    └── AutocompleteList
        └── AutocompleteGroup
            ├── AutocompleteGroupLabel
            └── AutocompleteItem
```

## Usage [#usage]

```tsx
import { useFilter, useListCollection } from "@ark-ui/react";
import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteGroup,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";
```

```tsx
const { contains } = useFilter({ sensitivity: "base" });
const { collection, filter } = useListCollection({
  initialItems: [
    { label: "Apple", value: "apple" },
    { label: "Banana", value: "banana" },
  ],
  filter: contains,
});

<Autocomplete
  collection={collection}
  onInputValueChange={({ inputValue }) => filter(inputValue)}
>
  <AutocompleteInput placeholder="Select an option" />
  <AutocompleteContent>
    <AutocompleteEmpty />
    <AutocompleteList>
      {items.map((item) => (
        <AutocompleteItem item={item} key={item.value}>
          {item.label}
        </AutocompleteItem>
      ))}
    </AutocompleteList>
  </AutocompleteContent>
</Autocomplete>
```

## Controlled [#controlled]

Control the selected value with `value` and `onValueChange` props.

<ComponentPreview componentName="autocomplete" fileName="example-controlled" />

## States [#states]

### Invalid [#invalid]

<ComponentPreview componentName="autocomplete" fileName="example-invalid" />

### Disabled [#disabled]

<ComponentPreview componentName="autocomplete" fileName="example-disabled" />

## Sizes [#sizes]

### Small [#small]

<ComponentPreview componentName="autocomplete" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="autocomplete" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="autocomplete" fileName="example-size-lg" />

## Examples [#examples]

### Group [#group]

<ComponentPreview componentName="autocomplete" fileName="example-group" />

### With Field [#with-field]

Use [Field](/docs/components/field) components to style with the field components.

<ComponentPreview componentName="autocomplete" fileName="example-with-field" />

### With clear button [#with-clear-button]

Pass `showClear` to `AutocompleteInput` to show a clear button.

<ComponentPreview componentName="autocomplete" fileName="example-with-clear-button" />

### With trigger [#with-trigger]

Pass `showTrigger` to `AutocompleteInput` to show the dropdown trigger button.

<ComponentPreview componentName="autocomplete" fileName="example-with-trigger" />

### With start icon [#with-start-icon]

Use `InputGroupAddon` to add a start icon to the input.

<ComponentPreview componentName="autocomplete" fileName="example-with-start-icon" />

## API Reference [#api-reference]

### Autocomplete [#autocomplete]

Root component.

| Prop                 | Type                                         | Default      |
| -------------------- | -------------------------------------------- | ------------ |
| `collection`         | `ListCollection<T>`                          | **required** |
| `value`              | `string[]`                                   | -            |
| `defaultValue`       | `string[]`                                   | -            |
| `onValueChange`      | `(details: ValueChangeDetails<T>) => void`   | -            |
| `onInputValueChange` | `(details: InputValueChangeDetails) => void` | -            |
| `disabled`           | `boolean`                                    | -            |
| `openOnClick`        | `boolean`                                    | `true`       |
| `lazyMount`          | `boolean`                                    | `true`       |
| `unmountOnExit`      | `boolean`                                    | `true`       |
| `className`          | `string`                                     | -            |

### AutocompleteInput [#autocompleteinput]

Input with dropdown trigger and clear button.

| Prop          | Type                   | Default |
| ------------- | ---------------------- | ------- |
| `size`        | `"sm" \| "md" \| "lg"` | `"md"`  |
| `showTrigger` | `boolean`              | `false` |
| `showClear`   | `boolean`              | `false` |
| `disabled`    | `boolean`              | -       |
| `className`   | `string`               | -       |

### AutocompleteContent [#autocompletecontent]

Holds the dropdown options. Displayed in a portal.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### AutocompleteGroup [#autocompletegroup]

Groups related items. Use with `groupBy` on the collection.

| Prop        | Type                  | Default |
| ----------- | --------------------- | ------- |
| `heading`   | `string \| ReactNode` | -       |
| `className` | `string`              | -       |

### AutocompleteGroupLabel [#autocompletegrouplabel]

Label for a group of options. Use inside `AutocompleteGroup`.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### AutocompleteItem [#autocompleteitem]

Single selectable option in the dropdown list.

| Prop        | Type      | Default      |
| ----------- | --------- | ------------ |
| `item`      | `T`       | **required** |
| `className` | `string`  | -            |
| `asChild`   | `boolean` | -            |

### AutocompleteEmpty [#autocompleteempty]

Shown when no options match the current filter. Use for empty state.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/combobox#api-reference).


# Avatar (/docs/components/avatar)



<ComponentPreview componentName="avatar" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/avatar
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Status](/docs/components/status)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/avatar.tsx" src="/avatar.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Avatar
├── AvatarImage
└── AvatarFallback

AvatarGroup
├── AvatarGroupCount
└── Avatar
    ├── AvatarImage
    ├── AvatarFallback
    └── AvatarBadge
```

## Usage [#usage]

```tsx
import { 
  Avatar, 
  AvatarImage, 
  AvatarFallback 
} from "@/components/ui/avatar";
```

```tsx
<Avatar>
  <AvatarImage src="https://github.com/vinihvc.png" />
  <AvatarFallback>VV</AvatarFallback>
</Avatar>
```

## Sizes [#sizes]

### Small [#small]

<ComponentPreview componentName="avatar" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="avatar" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="avatar" fileName="example-size-lg" />

## Examples [#examples]

### Avatar Group [#avatar-group]

<ComponentPreview componentName="avatar" fileName="example-group" />

### Badge [#badge]

<ComponentPreview componentName="avatar" fileName="example-with-status" />

### Badge with Icon [#badge-with-icon]

<ComponentPreview componentName="avatar" fileName="example-badge-with-icon" />

### Fallback with Icon [#fallback-with-icon]

<ComponentPreview componentName="avatar" fileName="example-fallback-icon" />

### Avatar Group Count [#avatar-group-count]

<ComponentPreview componentName="avatar" fileName="example-group-count" />

### Avatar Group Count Icon [#avatar-group-count-icon]

<ComponentPreview componentName="avatar" fileName="example-group-count-icon" />

### Avatar with Popover [#avatar-with-popover]

<ComponentPreview componentName="avatar" fileName="example-group-popover" />

### Avatar with Hover Card [#avatar-with-hover-card]

<ComponentPreview componentName="avatar" fileName="example-hover-card" />

### Custom Size [#custom-size]

Use `size-*` to set the size of the avatar.

<ComponentPreview componentName="avatar" fileName="example-size-custom" />

> You can use breakpoint utilities to change the size at different screen sizes.

```css
  md:size-4 lg:size-8
```

### Custom Radius [#custom-radius]

Use `rounded-*` to set the radius of the avatar.

<ComponentPreview componentName="avatar" fileName="example-custom-radius" />

> You can use breakpoint utilities to change the radius at different screen sizes.

```css
  md:rounded-full lg:rounded-lg
```

## API Reference [#api-reference]

### Avatar [#avatar]

Container for user or entity profile image. Supports sizes and fallback.

| Prop        | Type                   | Default |
| ----------- | ---------------------- | ------- |
| `size`      | `"sm" \| "md" \| "lg"` | `"md"`  |
| `className` | `string`               | `-`     |
| `asChild`   | `boolean`              | `false` |

### AvatarImage [#avatarimage]

Profile image. Shown when URL loads; fallback used on error.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### AvatarFallback [#avatarfallback]

Shown when the image fails to load or is loading. Often initials or icon.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### AvatarGroup [#avatargroup]

Groups avatars with overlap and optional count badge.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### AvatarGroupCount [#avatargroupcount]

Shows "+N" when more avatars exist than displayed.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### AvatarBadge [#avatarbadge]

Status or indicator badge overlaid on the avatar corner.

| Prop        | Type                                                             | Default     |
| ----------- | ---------------------------------------------------------------- | ----------- |
| `variant`   | `"default" \| "success" \| "info" \| "warning" \| "destructive"` | `"default"` |
| `className` | `string`                                                         | `-`         |
| `asChild`   | `boolean`                                                        | `false`     |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/avatar#api-reference).


# Badge (/docs/components/badge)



<ComponentPreview componentName="badge" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/badge
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Import the following variables into your CSS file
      </Step>

      <CodeCollapsibleWrapper>
        ```css
        @theme inline {
          --color-destructive-foreground: var(--destructive-foreground);
          --color-info: var(--info);
          --color-info-foreground: var(--info-foreground);
          --color-success: var(--success);
          --color-success-foreground: var(--success-foreground);
          --color-warning: var(--warning);
          --color-warning-foreground: var(--warning-foreground);
        }

        :root {
          --destructive-foreground: var(--color-red-700);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-700);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-700);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-700);
        }

        .dark {
          --destructive-foreground: var(--color-red-400);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-400);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-400);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-400);
        }
        ```
      </CodeCollapsibleWrapper>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/badge.tsx" src="/badge.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Badge } from "@/components/ui/badge";
```

```tsx
<Badge>Favorite</Badge>
```

## Variants [#variants]

### Default [#default]

<ComponentPreview componentName="badge" fileName="example-variant-default" />

### Secondary [#secondary]

<ComponentPreview componentName="badge" fileName="example-variant-secondary" />

### Outline [#outline]

<ComponentPreview componentName="badge" fileName="example-variant-outline" />

### Success [#success]

<ComponentPreview componentName="badge" fileName="example-variant-success" />

### Info [#info]

<ComponentPreview componentName="badge" fileName="example-variant-info" />

### Warning [#warning]

<ComponentPreview componentName="badge" fileName="example-variant-warning" />

### Destructive [#destructive]

<ComponentPreview componentName="badge" fileName="example-variant-destructive" />

## Sizes [#sizes]

The `size` prop controls the badge dimensions.

### Small [#small]

<ComponentPreview componentName="badge" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="badge" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="badge" fileName="example-size-lg" />

## Pill [#pill]

The `pill` prop creates fully rounded badges.

<ComponentPreview componentName="badge" fileName="example-pill" />

## Examples [#examples]

### With link [#with-link]

The `asChild` prop renders another element with badge styling.

<ComponentPreview componentName="badge" fileName="example-with-link" />

### With icon [#with-icon]

<ComponentPreview componentName="badge" fileName="example-with-icon" />

### With spinner [#with-spinner]

<ComponentPreview componentName="badge" fileName="example-with-spinner" />

### Custom color [#custom-color]

<ComponentPreview componentName="badge" fileName="example-custom-color" />

## API Reference [#api-reference]

### Badge [#badge]

Label, count, or status badge. Supports variants.

| Prop        | Type                                                                                         | Default     |
| ----------- | -------------------------------------------------------------------------------------------- | ----------- |
| `variant`   | `"default" \| "secondary" \| "outline" \| "success" \| "info" \| "warning" \| "destructive"` | `"default"` |
| `size`      | `"sm" \| "md" \| "lg"`                                                                       | `"md"`      |
| `className` | `string`                                                                                     | `-`         |
| `asChild`   | `boolean`                                                                                    | `false`     |


# Bottom Navigation (/docs/components/bottom-navigation)



<ComponentPreview componentName="bottom-navigation" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/bottom-navigation
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Tabs](/docs/components/tabs)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/bottom-navigation.tsx" src="/bottom-navigation.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
BottomNavigation
└── BottomNavigationList
    └── BottomNavigationItem
        ├── BottomNavigationItemIcon
        └── BottomNavigationItemLabel
```

## Usage [#usage]

```tsx
import {
  BottomNavigation,
  BottomNavigationList,
  BottomNavigationItem,
  BottomNavigationItemIcon,
  BottomNavigationItemLabel,
} from "@/components/ui/bottom-navigation";
```

```tsx
<BottomNavigation defaultValue="home">
  <BottomNavigationList>
    <BottomNavigationItem value="home">
      <BottomNavigationItemIcon>
        <HomeIcon />
      </BottomNavigationItemIcon>
      <BottomNavigationItemLabel>Home</BottomNavigationItemLabel>
    </BottomNavigationItem>
    <BottomNavigationItem value="notifications">
      <BottomNavigationItemIcon>
        <BellIcon />
      </BottomNavigationItemIcon>
      <BottomNavigationItemLabel>Notifications</BottomNavigationItemLabel>
    </BottomNavigationItem>
  </BottomNavigationList>
</BottomNavigation>
```

## Disclaimer [#disclaimer]

> Don't include `position: absolute` on the `BottomNavigationList`. It's just for the examples.

## Examples [#examples]

### Icon only [#icon-only]

Use `aria-label` on the `BottomNavigationItem` to give the item a label for screen readers.

<ComponentPreview componentName="bottom-navigation" fileName="example-icon-only" />

### With links [#with-links]

Use the `asChild` prop on `BottomNavigationItem` with `Link`.

<ComponentPreview componentName="bottom-navigation" fileName="example-with-links" />

## API Reference [#api-reference]

### BottomNavigation [#bottomnavigation]

Root wrapper for the bottom navigation bar.

| Prop            | Type                                    | Default |
| --------------- | --------------------------------------- | ------- |
| `value`         | `string`                                | `-`     |
| `defaultValue`  | `string`                                | `-`     |
| `onValueChange` | `(details: ValueChangeDetails) => void` | `-`     |
| `className`     | `string`                                | `-`     |
| `asChild`       | `boolean`                               | `false` |

### BottomNavigationList [#bottomnavigationlist]

Fixed bar at the bottom. Typically holds nav items.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### BottomNavigationItem [#bottomnavigationitem]

Single navigation link or button.

| Prop        | Type      | Default      |
| ----------- | --------- | ------------ |
| `value`     | `string`  | **required** |
| `disabled`  | `boolean` | `false`      |
| `className` | `string`  | `-`          |
| `asChild`   | `boolean` | `false`      |

### BottomNavigationItemIcon [#bottomnavigationitemicon]

Holds the item icon.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### BottomNavigationItemLabel [#bottomnavigationitemlabel]

Holds the item label text.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/tabs#api-reference).


# Breadcrumb (/docs/components/breadcrumb)



<ComponentPreview componentName="breadcrumb" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/breadcrumb
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/breadcrumb.tsx" src="/breadcrumb.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Breadcrumb
└── BreadcrumbList
    └── BreadcrumbItem
        ├── BreadcrumbLink
        ├── BreadcrumbPage
        ├── BreadcrumbSeparator
        └── BreadcrumbEllipsis
```

## Usage [#usage]

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@/components/ui/breadcrumb";
```

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/components">Components</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

## Examples [#examples]

### With custom separator [#with-custom-separator]

<ComponentPreview componentName="breadcrumb" fileName="example-custom-separator" />

### With links [#with-links]

<ComponentPreview componentName="breadcrumb" fileName="example-with-link" />

### Collapsed [#collapsed]

<ComponentPreview componentName="breadcrumb" fileName="example-collapsed" />

### With menu [#with-menu]

<ComponentPreview componentName="breadcrumb" fileName="example-with-menu" />

## API Reference [#api-reference]

### Breadcrumb [#breadcrumb]

Navigation landmark for the breadcrumb trail.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### BreadcrumbList [#breadcrumblist]

Ordered list of breadcrumb segments.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### BreadcrumbItem [#breadcrumbitem]

Wraps a single breadcrumb link or page.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### BreadcrumbLink [#breadcrumblink]

Link to a parent page in the hierarchy.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `href`      | `string`  | `-`     |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### BreadcrumbPage [#breadcrumbpage]

Current page. Not a link; marked with `aria-current="page"` for accessibility.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### BreadcrumbSeparator [#breadcrumbseparator]

Visual separator between segments.

| Prop        | Type              | Default        |
| ----------- | ----------------- | -------------- |
| `children`  | `React.ReactNode` | `ChevronRight` |
| `className` | `string`          | `-`            |
| `asChild`   | `boolean`         | `false`        |

### BreadcrumbEllipsis [#breadcrumbellipsis]

Shows when middle segments are collapsed.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |


# Button Group (/docs/components/button-group)



<ComponentPreview componentName="button-group" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/button-group
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Separator](/docs/components/separator)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/button-group.tsx" src="/button-group.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
ButtonGroup
└── Button or Input
├── ButtonGroupText
└── ButtonGroupSeparator
```

## Usage [#usage]

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

```tsx
<ButtonGroup> 
  <Button>
    Archive 
  </Button>
  <ButtonGroupSeparator />
  <Button>
    Report
  </Button>
</ButtonGroup>
```

## Accessibility [#accessibility]

* Use `aria-label` or `aria-labelledby` to label the group.

```tsx showLineNumbers
<ButtonGroup aria-label="Media controls">
  <Button>Play</Button>
  <Button>Pause</Button>
</ButtonGroup>
```

## Orientation [#orientation]

### Horizontal [#horizontal]

<ComponentPreview componentName="button-group" fileName="example-orientation-horizontal" />

### Vertical [#vertical]

<ComponentPreview componentName="button-group" fileName="example-orientation-vertical" />

## Examples [#examples]

### Nested [#nested]

<ComponentPreview componentName="button-group" fileName="example-nested" />

### Separator [#separator]

Buttons with variant `outline` do not need a separator since they have a border.

<ComponentPreview componentName="button-group" fileName="example-separator" />

### With Input [#with-input]

<ComponentPreview componentName="button-group" fileName="example-with-input" />

### With Menu [#with-menu]

<ComponentPreview componentName="button-group" fileName="example-with-menu" />

### With Popover [#with-popover]

A popover trigger button can be added to a button group for contextual information or actions.

<ComponentPreview componentName="button-group" fileName="example-with-popover" />

## API Reference [#api-reference]

### ButtonGroup [#buttongroup]

Groups buttons together. Uses fieldset for accessibility when applicable.

| Prop          | Type                         | Default        |
| ------------- | ---------------------------- | -------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
| `className`   | `string`                     | `-`            |
| `asChild`     | `boolean`                    | `false`        |

### ButtonGroupSeparator [#buttongroupseparator]

Visual divider between buttons. Uses [Separator](/docs/components/separator) internally.

| Prop          | Type                         | Default      |
| ------------- | ---------------------------- | ------------ |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` |
| `className`   | `string`                     | `-`          |
| `asChild`     | `boolean`                    | `false`      |


# Button (/docs/components/button)



<ComponentPreview componentName="button" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/button
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Spinner](/docs/components/spinner)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Import the following variables into your CSS file
      </Step>

      <CodeCollapsibleWrapper>
        ```css
        @theme inline {
          --color-destructive-foreground: var(--destructive-foreground);
          --color-info: var(--info);
          --color-info-foreground: var(--info-foreground);
          --color-success: var(--success);
          --color-success-foreground: var(--success-foreground);
          --color-warning: var(--warning);
          --color-warning-foreground: var(--warning-foreground);
        }

        :root {
          --destructive-foreground: var(--color-red-700);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-700);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-700);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-700);
        }

        .dark {
          --destructive-foreground: var(--color-red-400);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-400);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-400);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-400);
        }
        ```
      </CodeCollapsibleWrapper>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/button.tsx" src="/button.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

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

```tsx
<Button>Button</Button>
```

## Link [#link]

The `asChild` prop renders another element with button styling.

<ComponentPreview componentName="button" fileName="example-state-as-child" />

## States [#states]

### Disabled [#disabled]

<ComponentPreview componentName="button" fileName="example-disabled" />

### Loading [#loading]

<ComponentPreview componentName="button" fileName="example-loading" />

## Variants [#variants]

### Default [#default]

<ComponentPreview componentName="button" fileName="example-variant-default" />

### Outline [#outline]

<ComponentPreview componentName="button" fileName="example-variant-outline" />

### Secondary [#secondary]

<ComponentPreview componentName="button" fileName="example-variant-secondary" />

### Ghost [#ghost]

<ComponentPreview componentName="button" fileName="example-variant-ghost" />

### Link [#link-1]

<ComponentPreview componentName="button" fileName="example-variant-link" />

### Destructive [#destructive]

<ComponentPreview componentName="button" fileName="example-variant-destructive" />

## Sizes [#sizes]

### Extra Small [#extra-small]

<ComponentPreview componentName="button" fileName="example-size-xs" />

### Small [#small]

<ComponentPreview componentName="button" fileName="example-size-sm" />

### Large [#large]

<ComponentPreview componentName="button" fileName="example-size-lg" />

### Extra Large [#extra-large]

<ComponentPreview componentName="button" fileName="example-size-xl" />

## Pill [#pill]

<ComponentPreview componentName="button" fileName="example-pill" />

## Disabling click effect [#disabling-click-effect]

<ComponentPreview componentName="button" fileName="example-no-click-effect" />

## Examples [#examples]

### Icon only [#icon-only]

Add `aria-label` prop to the button so screen readers can identify the button.

<ComponentPreview componentName="button" fileName="example-icon" />

### With icon [#with-icon]

<ComponentPreview componentName="button" fileName="example-with-icon" />

### Touch hitbox [#touch-hitbox]

For increasing the tap target area, use [Hitbox](/docs/utilities/hitbox).

<ComponentPreview componentName="button" fileName="example-hitbox" />

### Custom color [#custom-color]

<ComponentPreview componentName="button" fileName="example-custom-color" />

## API Reference [#api-reference]

| Prop          | Type                                                                                                    | Default     |
| ------------- | ------------------------------------------------------------------------------------------------------- | ----------- |
| `variant`     | `"default" \| "outline" \| "secondary" \| "ghost" \| "link" \| "destructive"`                           | `"default"` |
| `size`        | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "icon-xs" \| "icon-sm" \| "icon-md" \| "icon-lg" \| "icon-xl"` | `"md"`      |
| `clickEffect` | `boolean`                                                                                               | `true`      |
| `isLoading`   | `boolean`                                                                                               | `false`     |
| `className`   | `string`                                                                                                | `-`         |
| `asChild`     | `boolean`                                                                                               | `false`     |


# Calendar (/docs/components/calendar)



<ComponentPreview componentName="calendar" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/calendar
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

         and 

        [Native Select](/docs/components/native-select)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/calendar.tsx" src="/calendar.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Calendar
├── CalendarViewControl
│   ├── CalendarPrevTrigger
│   ├── CalendarMonthSelect
│   ├── CalendarYearSelect
│   ├── CalendarViewDate
│   └── CalendarNextTrigger
└── CalendarTable
    ├── CalendarWeekDays
    └── CalendarTableDays
```

## Usage [#usage]

```tsx
import {
  Calendar,
  CalendarNextTrigger,
  CalendarPrevTrigger,
  CalendarTable,
  CalendarTableDays,
  CalendarViewControl,
  CalendarViewDate,
  CalendarWeekDays,
} from "@/components/ui/calendar";
```

```tsx showLineNumbers
<Calendar>
  <CalendarViewControl>
    <CalendarPrevTrigger />
    <CalendarViewDate />
    <CalendarNextTrigger />
  </CalendarViewControl>
  <CalendarTable>
    <CalendarWeekDays />
    <CalendarTableDays />
  </CalendarTable>
</Calendar>
```

## Controlled [#controlled]

<ComponentPreview componentName="calendar" fileName="example-controlled" />

## Examples [#examples]

### Date Range [#date-range]

<ComponentPreview componentName="calendar" fileName="example-range" />

### Month and Year Selector [#month-and-year-selector]

<ComponentPreview componentName="calendar" fileName="example-month-year-selector" />

### With Presets [#with-presets]

<ComponentPreview componentName="calendar" fileName="example-presets" hasMaxHeight="false" />

### Multiple Months [#multiple-months]

<ComponentPreview componentName="calendar" fileName="example-multiple-months" />

### Min and Max [#min-and-max]

<ComponentPreview componentName="calendar" fileName="example-min-max" />

### Select Today [#select-today]

<ComponentPreview componentName="calendar" fileName="example-select-today" hasMaxHeight="false" />

### Fixed Weeks [#fixed-weeks]

<ComponentPreview componentName="calendar" fileName="example-fixed-weeks" />

### Booked Dates [#booked-dates]

<ComponentPreview componentName="calendar" fileName="example-booked-dates" />

### Custom Cell Size [#custom-cell-size]

Use `[--cell-size:--spacing("value")]` to set the size of the calendar cells.

Default value is `--spacing(9)`.

<ComponentPreview componentName="calendar" fileName="example-custom-cell-size" />

> You can use breakpoint utilities to change the cell size at different screen sizes.

```css
  md:[--cell-size:--spacing(10)] lg:[--cell-size:--spacing(12)]
```

## API Reference [#api-reference]

### Calendar [#calendar]

Root component. Manages date view, selection, and navigation.

| Prop                   | Type                                    | Default    |
| ---------------------- | --------------------------------------- | ---------- |
| `value`                | `DateValue[]`                           | -          |
| `defaultValue`         | `DateValue[]`                           | -          |
| `onValueChange`        | `(details: ValueChangeDetails) => void` | -          |
| `selectionMode`        | `"single" \| "range" \| "multiple"`     | `"single"` |
| `min`                  | `DateValue`                             | -          |
| `max`                  | `DateValue`                             | -          |
| `isDateUnavailable`    | `(date: DateValue) => boolean`          | -          |
| `fixedWeeks`           | `boolean`                               | `false`    |
| `outsideDaySelectable` | `boolean`                               | `false`    |
| `numOfMonths`          | `number`                                | `1`        |
| `className`            | `string`                                | -          |
| `asChild`              | `boolean`                               | `false`    |

| CSS Variable  | Default        |
| ------------- | -------------- |
| `--cell-size` | `--spacing(9)` |

### CalendarViewControl [#calendarviewcontrol]

Holds prev/next buttons and month/year selects.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### CalendarMonthSelect [#calendarmonthselect]

Month selector dropdown. Uses NativeSelect internally.

| Prop        | Type                | Default   |
| ----------- | ------------------- | --------- |
| `format`    | `"short" \| "long"` | `"short"` |
| `className` | `string`            | -         |

### CalendarYearSelect [#calendaryearselect]

Year selector dropdown.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### CalendarTable [#calendartable]

Table layout for the calendar day grid.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### CalendarWeekDays [#calendarweekdays]

Header row with week day names (Sun–Sat).

| Prop        | Type                            | Default    |
| ----------- | ------------------------------- | ---------- |
| `format`    | `"narrow" \| "short" \| "long"` | `"narrow"` |
| `className` | `string`                        | -          |

### CalendarTableDays [#calendartabledays]

Body with day cells for the current month.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### CalendarTableNextMonth [#calendartablenextmonth]

Body for additional month(s).

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `months`    | `number` | `1`     |
| `className` | `string` | -       |

### CalendarTableCell [#calendartablecell]

Single day cell. Clickable for selection. Shows disabled/outside styling.

| Prop        | Type        | Default |
| ----------- | ----------- | ------- |
| `value`     | `DateValue` | -       |
| `className` | `string`    | -       |

### parseDate [#parsedate]

Utility for parsing dates.

```tsx
import { parseDate } from "@/components/ui/calendar";

parseDate(new Date());
parseDate("2024-01-15");
parseDate(Date.now());
```

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/date-picker#api-reference).


# Card (/docs/components/card)



<ComponentPreview componentName="card" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/card
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/card.tsx" src="/card.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Card
├── CardMedia
├── CardHeader
│   ├── CardTitle
│   ├── CardDescription
│   └── CardAction
├── CardContent
└── CardFooter
```

## Usage [#usage]

```tsx
import { 
  Card, 
  CardContent, 
  CardDescription, 
  CardFooter, 
  CardHeader, 
  CardTitle, 
  CardAction,
  CardMedia,
} from "@/components/ui/card";
```

```tsx
<Card>
  <CardMedia />
  <CardHeader>
    <CardTitle />
    <CardDescription />
    <CardAction />
  </CardHeader>
  <CardContent />
  <CardFooter />
</Card>
```

## Title & Description [#title--description]

`CardHeader` supports two usage patterns:

### Using props [#using-props]

Pass `title` and `description` props directly to `CardHeader`.

```tsx showLineNumbers
<CardHeader title="Card Title" description="Card description">
  <CardAction />
</CardHeader>
```

> This approach does not require `CardTitle` or `CardDescription` components.

### Using components [#using-components]

Use `CardTitle` and `CardDescription` as children for more control.

```tsx showLineNumbers
<CardHeader>
  <CardTitle>Card Title</CardTitle>
  <CardDescription>Card description</CardDescription>
  <CardAction />
</CardHeader>
```

## Examples [#examples]

### Product card [#product-card]

<ComponentPreview componentName="card" fileName="example-product" />

### Icon card [#icon-card]

<ComponentPreview componentName="card" fileName="example-icon" />

### Custom spacing [#custom-spacing]

The `[--space:--spacing("value")]` on `Card` controls the internal spacing.

Default spacing is `--spacing(6)`.

<ComponentPreview componentName="card" fileName="example-custom-spacing" />

> You can use breakpoint utilities to change the internal spacing at different screen sizes.

```css
  md:[--space:--spacing(6)] lg:[--space:--spacing(8)]
```

## API Reference [#api-reference]

### Card [#card]

Root wrapper for card layout.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

| CSS Variable | Default        |
| ------------ | -------------- |
| `--space`    | `--spacing(6)` |

### CardMedia [#cardmedia]

Image, video, or media area. Often full-width at top.

| Prop        | Type                             | Default     |
| ----------- | -------------------------------- | ----------- |
| `variant`   | `"default" \| "icon" \| "image"` | `"default"` |
| `className` | `string`                         | `-`         |
| `asChild`   | `boolean`                        | `false`     |

### CardHeader [#cardheader]

Header area. Typically holds title and optional actions.

| Prop          | Type      | Default |
| ------------- | --------- | ------- |
| `title`       | `string`  | `-`     |
| `description` | `string`  | `-`     |
| `className`   | `string`  | `-`     |
| `asChild`     | `boolean` | `false` |

### CardTitle [#cardtitle]

Card title or heading. Bold by default.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### CardDescription [#carddescription]

Card description or body text. Muted foreground for hierarchy.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### CardAction [#cardaction]

Action button or link in the card header.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### CardContent [#cardcontent]

Main body content of the card.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### CardFooter [#cardfooter]

Footer area. Typically holds secondary actions or metadata.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |


# Carousel (/docs/components/carousel)



<ComponentPreview componentName="carousel" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/carousel
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/carousel.tsx" src="/carousel.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Carousel
├── CarouselContent
│   └── CarouselItem
├── CarouselControl
│   ├── CarouselPrevious
│   └── CarouselNext
└── CarouselIndicatorGroup
    └── CarouselIndicator
```

## Usage [#usage]

```tsx
import { 
  Carousel,
  CarouselControl,
  CarouselItem,
  CarouselContent,
  CarouselIndicator,
  CarouselIndicatorGroup,
  CarouselNext,
  CarouselPrevious,
} from "@/components/ui/carousel"; 
```

```tsx
<Carousel>
  <CarouselControl>
    <CarouselPrevious>Previous</CarouselPrevious>
    <CarouselNext>Next</CarouselNext>
  </CarouselControl>
  <CarouselContent>
    <CarouselItem />
    <CarouselItem />
  </CarouselContent>
</Carousel>
```

## Orientation [#orientation]

### Horizontal [#horizontal]

<ComponentPreview componentName="carousel" fileName="example-orientation-horizontal" />

### Vertical [#vertical]

<ComponentPreview componentName="carousel" fileName="example-orientation-vertical" />

## Thumbnail Indicators [#thumbnail-indicators]

Render each thumbnail inside `CarouselIndicator` to create a visual preview of each slide.

### Horizontal [#horizontal-1]

<ComponentPreview componentName="carousel" fileName="example-thumbnail-indicator" />

### Vertical [#vertical-1]

<ComponentPreview componentName="carousel" fileName="example-thumbnail-indicator-vertical" />

## Examples [#examples]

### Autoplay [#autoplay]

Use `autoplay` props on `Carousel` to make the carousel play automatically.

<ComponentPreview componentName="carousel" fileName="example-autoplay" />

### Loop [#loop]

Use `loop` prop to make the carousel loop.

<ComponentPreview componentName="carousel" fileName="example-loop" />

### Controlled [#controlled]

Use `page` and `onPageChange` props to control the carousel state programmatically.

<ComponentPreview componentName="carousel" fileName="example-controlled" />

### Slides Per Page [#slides-per-page]

Display multiple slides simultaneously by setting the `slidesPerPage` prop on `Carousel`.

<ComponentPreview componentName="carousel" fileName="example-slides-per-page" />

### Spacing [#spacing]

Control the gap between slides using the `spacing` prop on `Carousel`.

<ComponentPreview componentName="carousel" fileName="example-spacing" />

### Mouse Drag [#mouse-drag]

To allow mouse drag, set the `allowMouseDrag` prop on `Carousel`.

<ComponentPreview componentName="carousel" fileName="example-mouse-drag" />

## API Reference [#api-reference]

### Carousel [#carousel]

Root component. Manages slide state and navigation.

| Prop             | Type                           | Default        |
| ---------------- | ------------------------------ | -------------- |
| `slideCount`     | `number`                       | **required**   |
| `allowMouseDrag` | `boolean`                      | `false`        |
| `autoplay`       | `boolean \| { delay: number }` | `false`        |
| `defaultPage`    | `number`                       | `0`            |
| `loop`           | `boolean`                      | `false`        |
| `orientation`    | `"horizontal" \| "vertical"`   | `"horizontal"` |
| `page`           | `number`                       | `-`            |
| `slidesPerPage`  | `number`                       | `1`            |
| `slidesPerMove`  | `number \| 'auto'`             | `'auto'`       |
| `spacing`        | `string`                       | `"16px"`       |
| `padding`        | `number`                       | `0`            |
| `className`      | `string`                       | `-`            |

### CarouselContent [#carouselcontent]

Wraps all slides. Handles layout and transitions.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### CarouselItem [#carouselitem]

Wraps a single slide.

| Prop        | Type                           | Default      |
| ----------- | ------------------------------ | ------------ |
| `index`     | `number`                       | **required** |
| `snapAlign` | `"start" \| "center" \| "end"` | `"start"`    |
| `className` | `string`                       | `-`          |
| `asChild`   | `boolean`                      | `false`      |

### CarouselControl [#carouselcontrol]

Holds prev/next navigation buttons.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### CarouselPrevious [#carouselprevious]

Goes to the previous slide.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### CarouselNext [#carouselnext]

Goes to the next slide.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### CarouselIndicatorGroup [#carouselindicatorgroup]

Holds slide indicator dots or pills.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### CarouselIndicator [#carouselindicator]

Indicator for a slide. Click to jump to that slide.

| Prop        | Type      | Default      |
| ----------- | --------- | ------------ |
| `index`     | `number`  | **required** |
| `readOnly`  | `boolean` | `false`      |
| `className` | `string`  | `-`          |
| `asChild`   | `boolean` | `false`      |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/carousel#api-reference).


# Chart (/docs/components/chart)



<ComponentPreview componentName="chart" />

For more complete, copy-ready setups:

Browse the Charts Examples (soon).

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/chart
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install recharts
      ```

      <Step>
        Import the following chart color variables into your CSS file (if they are not already in your theme)
      </Step>

      <CodeCollapsibleWrapper>
        ```css
        @theme inline {
          --color-chart-1: var(--chart-1);
          --color-chart-2: var(--chart-2);
          --color-chart-3: var(--chart-3);
          --color-chart-4: var(--chart-4);
          --color-chart-5: var(--chart-5);
        }

        :root {
          --chart-1: var(--color-orange-600);
          --chart-2: var(--color-teal-600);
          --chart-3: var(--color-cyan-900);
          --chart-4: var(--color-amber-400);
          --chart-5: var(--color-amber-500);
        }

        .dark {
          --chart-1: var(--color-blue-700);
          --chart-2: var(--color-emerald-500);
          --chart-3: var(--color-amber-500);
          --chart-4: var(--color-purple-500);
          --chart-5: var(--color-rose-500);
        }
        ```
      </CodeCollapsibleWrapper>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/chart.tsx" src="/chart.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
ChartContainer
├── ChartStyle
├── Recharts surface (BarChart, LineChart, …)
├── ChartTooltip
│   └── ChartTooltipContent
└── ChartLegend
    └── ChartLegendContent
```

## Component [#component]

These pieces follow the familiar [shadcn/ui](https://ui.shadcn.com/docs/components/base/chart) chart pattern—container, tooltips, and legend helpers around standard Recharts charts—restyled and wired to Shark UI tokens and imports so the result feels native to this kit.

```tsx
import { Bar, BarChart } from "recharts"
import { ChartContainer, ChartTooltip, ChartTooltipContent } from "@/components/ui/chart"

export const MyChart = () => {
  return (
    <ChartContainer>
      <BarChart data={data}>
        <Bar dataKey="value" />
        <ChartTooltip content={(props) => <ChartTooltipContent {...props} />} />
      </BarChart>
    </ChartContainer>
  )
}
```

## Usage [#usage]

Walk through a small bar chart: sample data, a shared config object, then layers for grid, axis, tooltip, and legend.

### Start with data [#start-with-data]

Shape the rows however you like; `dataKey` maps columns to bars, lines, or areas. This set tracks desktop versus mobile counts per month:

```tsx
const chartData = [
  { month: "January", desktop: 186, mobile: 80 },
  { month: "February", desktop: 305, mobile: 200 },
  { month: "March", desktop: 237, mobile: 120 },
  { month: "April", desktop: 73, mobile: 190 },
  { month: "May", desktop: 209, mobile: 130 },
  { month: "June", desktop: 214, mobile: 140 },
]
```

### Add a chart config [#add-a-chart-config]

`ChartConfig` is metadata: human-readable labels, optional icons, and color tokens. It stays separate from the data array so several charts can reuse the same palette and copy.

```tsx
import { type ChartConfig } from "@/components/ui/chart"

const chartConfig = {
  desktop: {
    label: "Desktop",
    color: "#2563eb",
  },
  mobile: {
    label: "Mobile",
    color: "#60a5fa",
  },
} satisfies ChartConfig
```

### Render the chart [#render-the-chart]

Pass `config` into `ChartContainer`. Give the container a **minimum height** (for example `min-h-[200px]`) or a fixed height so Recharts can measure the SVG responsively.

```tsx
"use client"

import { Bar, BarChart } from "recharts"
import { ChartContainer, type ChartConfig } from "@/components/ui/chart"

<ChartContainer config={chartConfig} className="min-h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>
```

### Add a grid [#add-a-grid]

Import `CartesianGrid` from Recharts and nest it inside the chart. Horizontal stripes alone often read cleaner than a full mesh:

```tsx
import { Bar, BarChart, CartesianGrid } from "recharts"

<ChartContainer config={chartConfig} className="min-h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>
```

### Add an axis [#add-an-axis]

Use `XAxis` (and `YAxis` when you need one) for categories and ticks. Here ticks are shortened and decorative lines are hidden for a lighter look:

```tsx
import { Bar, BarChart, CartesianGrid, XAxis } from "recharts"

<ChartContainer config={chartConfig} className="h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <XAxis
      dataKey="month"
      tickLine={false}
      tickMargin={10}
      axisLine={false}
      tickFormatter={(value) => value.slice(0, 3)}
    />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>
```

### Add a tooltip [#add-a-tooltip]

Shark’s tooltip pair reads names, swatches, and values from `chartConfig` automatically:

```tsx
import { ChartTooltip, ChartTooltipContent } from "@/components/ui/chart"

<ChartContainer config={chartConfig} className="h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <XAxis
      dataKey="month"
      tickLine={false}
      tickMargin={10}
      axisLine={false}
      tickFormatter={(value) => value.slice(0, 3)}
    />
    <ChartTooltip content={(props) => <ChartTooltipContent {...props} />} />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>
```

### Add a legend [#add-a-legend]

`ChartLegend` with `ChartLegendContent` mirrors the same config entries:

```tsx
import { ChartLegend, ChartLegendContent } from "@/components/ui/chart"

<ChartContainer config={chartConfig} className="h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <XAxis
      dataKey="month"
      tickLine={false}
      tickMargin={10}
      axisLine={false}
      tickFormatter={(value) => value.slice(0, 3)}
    />
    <ChartTooltip content={(props) => <ChartTooltipContent {...props} />} />
    <ChartLegend content={<ChartLegendContent />} />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>
```

## Chart config [#chart-config]

Treat `ChartConfig` as the **presentation contract** for your series keys: labels for tooltips and legends, optional Lucide (or other) icons, and either a single `color` string or a `theme` map for light and dark. Data arrays stay focused on numbers and categories.

Because config is independent of rows, you can fetch remote data in one shape while keeping stable color tokens in code, share one config across a dashboard, or swap palettes without touching API responses.

```tsx
import { Monitor } from "lucide-react"
import { type ChartConfig } from "@/components/ui/chart"

const chartConfig = {
  desktop: {
    label: "Desktop",
    icon: Monitor,
    color: "#2563eb",
    theme: {
      light: "#2563eb",
      dark: "#dc2626",
    },
  },
} satisfies ChartConfig
```

Use `color` for a single value that works in both themes, or `theme` with `light` / `dark` keys when the swatch should diverge.

## Theming [#theming]

You can theme series with CSS variables (ideal alongside Shark’s tokens), raw color strings in any supported format, or a mix.

### CSS variables [#css-variables]

Shark’s default theme already defines `--chart-1` through `--chart-5` in `globals.css`; see [Styling](/docs/styling) for how those slots fit the rest of the design system. Point config entries at those variables so charts track global palette tweaks:

```tsx
const chartConfig = {
  desktop: {
    label: "Desktop",
    color: "var(--chart-1)",
  },
  mobile: {
    label: "Mobile",
    color: "var(--chart-2)",
  },
} satisfies ChartConfig
```

### Hex, HSL, or OKLCH [#hex-hsl-or-oklch]

Inline literals work when you do not need shared tokens:

```tsx
const chartConfig = {
  desktop: { label: "Desktop", color: "#2563eb" },
  mobile: { label: "Mobile", color: "hsl(220, 98%, 61%)" },
  tablet: { label: "Tablet", color: "oklch(0.5 0.2 240)" },
  laptop: { label: "Laptop", color: "var(--chart-2)" },
} satisfies ChartConfig
```

### Applying colors in markup and data [#applying-colors-in-markup-and-data]

The container exposes `var(--color-<key>)` for each config key. Use that placeholder anywhere Recharts or Tailwind can read a color:

* **Series elements:** `<Bar dataKey="desktop" fill="var(--color-desktop)" />`
* **Data-driven fills:** `{ browser: "chrome", visitors: 275, fill: "var(--color-chrome)" }` with matching config keys
* **Tailwind utilities:** `<LabelList className="fill-[--color-desktop]" />`

## Tooltip [#tooltip]

Pair `ChartTooltip` with `ChartTooltipContent` to get a styled surface that pulls series colors and labels from `chartConfig`. Pass tooltip state from Recharts by using a render function for `content` and spreading those props into `ChartTooltipContent`. Toggle the label row or the color chip with props, and switch the indicator shape between dot, line, and dashed styles.

```tsx
import { ChartTooltip, ChartTooltipContent } from "@/components/ui/chart"

<ChartTooltip content={(props) => <ChartTooltipContent {...props} />} />
```

### Tooltip props [#tooltip-props]

| Prop            | Type                          |
| --------------- | ----------------------------- |
| `labelKey`      | string                        |
| `nameKey`       | string                        |
| `indicator`     | `"dot" \| "line" \| "dashed"` |
| `hideLabel`     | boolean                       |
| `hideIndicator` | boolean                       |

### Custom label and name keys [#custom-label-and-name-keys]

When the tooltip should read from different fields than the default mapping, pass `labelKey` and `nameKey` so the header and each row title resolve correctly:

```tsx
const chartData = [
  { browser: "chrome", visitors: 187, fill: "var(--color-chrome)" },
  { browser: "safari", visitors: 200, fill: "var(--color-safari)" },
]

const chartConfig = {
  visitors: {
    label: "Total Visitors",
  },
  chrome: {
    label: "Chrome",
    color: "var(--chart-1)",
  },
  safari: {
    label: "Safari",
    color: "var(--chart-2)",
  },
} satisfies ChartConfig

<ChartTooltip
  content={(props) => (
    <ChartTooltipContent {...props} labelKey="visitors" nameKey="browser" />
  )}
/>
```

## Legend [#legend]

`ChartLegend` delegates rendering to `ChartLegendContent`, which builds items from the same config metadata as the tooltip.

```tsx
import { ChartLegend, ChartLegendContent } from "@/components/ui/chart"

<ChartLegend content={<ChartLegendContent />} />
```

### Custom name key [#custom-name-key]

When legend entries should track a field on each datum (for example `browser`), set `nameKey`:

```tsx
const chartData = [
  { browser: "chrome", visitors: 187, fill: "var(--color-chrome)" },
  { browser: "safari", visitors: 200, fill: "var(--color-safari)" },
]

const chartConfig = {
  chrome: {
    label: "Chrome",
    color: "var(--chart-1)",
  },
  safari: {
    label: "Safari",
    color: "var(--chart-2)",
  },
} satisfies ChartConfig

<ChartLegend content={<ChartLegendContent nameKey="browser" />} />
```

## Accessibility [#accessibility]

Recharts’ `accessibilityLayer` opt-in wires keyboard traversal and screen-reader semantics into the chart canvas. Turn it on for interactive or data-critical views; leave it off for purely decorative thumbnails if you need to avoid extra focus targets.

```tsx
<BarChart accessibilityLayer data={chartData}>
  {/* children */}
</BarChart>
```

```tsx
<LineChart accessibilityLayer data={chartData}>
  {/* children */}
</LineChart>
```

***

For every prop on primitives such as `Bar`, `Line`, or `XAxis`, refer to the [Recharts API reference](https://recharts.github.io/en-US/api).


# Checkbox (/docs/components/checkbox)



<ComponentPreview componentName="checkbox" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/checkbox
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/checkbox.tsx" src="/checkbox.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Checkbox } from "@/components/ui/checkbox";
```

```tsx showLineNumbers
<Checkbox />
```

## Controlled [#controlled]

Use the `checked` and `onCheckedChange` props to control the checkbox state programmatically.

<ComponentPreview componentName="checkbox" fileName="example-controlled" />

## States [#states]

### Invalid [#invalid]

Use the `invalid` prop to indicate an invalid state.

<ComponentPreview componentName="checkbox" fileName="example-invalid" />

### Disabled [#disabled]

Use the `disabled` prop to disable the checkbox.

<ComponentPreview componentName="checkbox" fileName="example-disabled" />

## Examples [#examples]

### With Description [#with-description]

<ComponentPreview componentName="checkbox" fileName="example-with-description" />

### Indeterminate [#indeterminate]

<ComponentPreview componentName="checkbox" fileName="example-indeterminate" />

### Group [#group]

<ComponentPreview componentName="checkbox" fileName="example-checkbox-group" />

### Card Style [#card-style]

<ComponentPreview componentName="checkbox" fileName="example-card" />

## API Reference [#api-reference]

### Checkbox [#checkbox]

Checkbox control for boolean or multi-select state.

| Prop              | Type                                          | Default |
| ----------------- | --------------------------------------------- | ------- |
| `checked`         | `boolean \| 'indeterminate'`                  | `-`     |
| `defaultChecked`  | `boolean`                                     | `false` |
| `disabled`        | `boolean`                                     | `false` |
| `checked`         | `boolean \| 'indeterminate'`                  | `-`     |
| `onCheckedChange` | `({ checked }: CheckedChangeDetails) => void` | `-`     |
| `className`       | `string`                                      | `-`     |

### CheckboxGroup [#checkboxgroup]

Groups related checkboxes with consistent layout.

| Prop            | Type                                    | Default |
| --------------- | --------------------------------------- | ------- |
| `value`         | `string[]`                              | `-`     |
| `defaultValue`  | `string[]`                              | `[]`    |
| `onValueChange` | `(details: ValueChangeDetails) => void` | `-`     |
| `className`     | `string`                                | `-`     |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/checkbox#api-reference).


# Circular Progress (/docs/components/circular-progress)



<ComponentPreview componentName="circular-progress" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/circular-progress
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/circular-progress.tsx" src="/circular-progress.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

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

```tsx
<CircularProgress value={66} />
```

## Controlled [#controlled]

<ComponentPreview componentName="circular-progress" fileName="example-controlled" />

## Examples [#examples]

### With value [#with-value]

<ComponentPreview componentName="circular-progress" fileName="example-with-value" />

### Indeterminate [#indeterminate]

<ComponentPreview componentName="circular-progress" fileName="example-indeterminate" />

### Custom Size [#custom-size]

Use the `size` prop to change the circular progress indicator size.

<ComponentPreview componentName="circular-progress" fileName="example-size" />

### Custom Thickness [#custom-thickness]

Use the `thickness` prop to control the ring stroke width.

<ComponentPreview componentName="circular-progress" fileName="example-thickness" />

## API Reference [#api-reference]

### CircularProgress [#circularprogress]

Root element of the circular progress indicator.

| Prop            | Type                                    | Default |
| --------------- | --------------------------------------- | ------- |
| `value`         | `number \| null`                        | -       |
| `defaultValue`  | `number`                                | -       |
| `onValueChange` | `(details: ValueChangeDetails) => void` | -       |
| `indeterminate` | `boolean`                               | `false` |
| `size`          | `number`                                | `32`    |
| `thickness`     | `number`                                | `4`     |
| `className`     | `string`                                | -       |

### CircularProgressValue [#circularprogressvalue]

Displays the current progress value text.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/react/docs/components/progress-circular#api-reference).


# Circular Slider (/docs/components/circular-slider)



<ComponentPreview componentName="circular-slider" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/circular-slider
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Field](/docs/components/field)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/circular-slider.tsx" src="/circular-slider.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { CircularSlider } from "@/components/ui/circular-slider";
```

```tsx
<CircularSlider defaultValue={45} />
```

## Controlled [#controlled]

<ComponentPreview componentName="circular-slider" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

<ComponentPreview componentName="circular-slider" fileName="example-disabled" />

## Examples [#examples]

### Size [#size]

Use the `size` prop to change the slider dimensions.

<ComponentPreview componentName="circular-slider" fileName="example-size" />

### Thickness [#thickness]

Use the `thickness` prop to change the progress ring thickness.

<ComponentPreview componentName="circular-slider" fileName="example-thickness" />

### With markers [#with-markers]

Use `markers` to display clock-style tick marks.

<ComponentPreview componentName="circular-slider" fileName="example-with-markers" />

### With step [#with-step]

Use `markersAtSteps` with `step` to align markers with step positions.

<ComponentPreview componentName="circular-slider" fileName="example-step" />

### Show value [#show-value]

Use `CircularSliderValue` to show the current value. The `prefix` and `suffix` props customize the display.

<ComponentPreview componentName="circular-slider" fileName="example-with-value" />

### Custom markers [#custom-markers]

Pass a `number[]` to `markers` for custom angles.

<ComponentPreview componentName="circular-slider" fileName="example-custom-markers" />

## API Reference [#api-reference]

### CircularSlider [#circularslider]

Root component. Manages angle selection and value.

| Prop             | Type                                    | Default |
| ---------------- | --------------------------------------- | ------- |
| `value`          | `number`                                | -       |
| `defaultValue`   | `number`                                | `0`     |
| `onValueChange`  | `(details: ValueChangeDetails) => void` | -       |
| `step`           | `number`                                | `1`     |
| `disabled`       | `boolean`                               | -       |
| `size`           | `number`                                | `120`   |
| `thickness`      | `number`                                | `6`     |
| `markers`        | `boolean \| number[]`                   | -       |
| `markersAtSteps` | `boolean`                               | `false` |
| `className`      | `string`                                | -       |

### CircularSliderValue [#circularslidervalue]

Shows the current angle value (degrees or custom format).

| Prop        | Type                        | Default |
| ----------- | --------------------------- | ------- |
| `prefix`    | `React.ReactNode \| string` | -       |
| `suffix`    | `React.ReactNode \| string` | -       |
| `className` | `string`                    | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/react/docs/components/angle-slider).


# Clipboard (/docs/components/clipboard)



<ComponentPreview componentName="clipboard" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/clipboard
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Input](/docs/components/input)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/clipboard.tsx" src="/clipboard.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Clipboard
├── ClipboardTrigger
│   └── ClipboardIndicator
├── ClipboardInput
└── ClipboardValue
```

## Usage [#usage]

```tsx
import { 
  Clipboard, 
  ClipboardTrigger, 
  ClipboardIndicator 
} from "@/components/ui/clipboard";
```

```tsx
<Clipboard value="https://x.com/vinihvc">
  <ClipboardTrigger asChild>
    <Button size="icon-md">
      <ClipboardIndicator />
    </Button>
  </ClipboardTrigger>
</Clipboard>
```

## Controlled [#controlled]

<ComponentPreview componentName="clipboard" fileName="example-controlled" />

## Examples [#examples]

### Icon Only [#icon-only]

<ComponentPreview componentName="clipboard" fileName="example-icon-only" />

### Different Icons [#different-icons]

<ComponentPreview componentName="clipboard" fileName="example-different-icon" />

### Value Text [#value-text]

Use `ClipboardValue` component to display the value as text instead of an input field.

<ComponentPreview componentName="clipboard" fileName="example-value-text" />

### Custom Timeout [#custom-timeout]

Use the `timeout` prop on `Clipboard` to customize how long the copied state is shown.

<ComponentPreview componentName="clipboard" fileName="example-custom-timeout" />

## API Reference [#api-reference]

### Clipboard [#clipboard]

Root wrapper. Manages copy state and value.

| Prop        | Type     | Default      |
| ----------- | -------- | ------------ |
| `value`     | `string` | **required** |
| `timeout`   | `number` | `2000`       |
| `className` | `string` | `-`          |

### ClipboardTrigger [#clipboardtrigger]

Triggers copy to clipboard on click.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### ClipboardInput [#clipboardinput]

Input showing the value to copy. Often hidden or read-only.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### ClipboardIndicator [#clipboardindicator]

Icon that changes based on copy state.

| Prop        | Type        | Default     |
| ----------- | ----------- | ----------- |
| `copied`    | `ReactNode` | `CheckIcon` |
| `className` | `string`    | `-`         |

### ClipboardValue [#clipboardvalue]

Text display of the value. Use when input is not needed.

| Prop        | Type                                   | Default |
| ----------- | -------------------------------------- | ------- |
| `size`      | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"`  |
| `className` | `string`                               | `-`     |
| `asChild`   | `boolean`                              | `false` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/clipboard#api-reference).


# Collapsible (/docs/components/collapsible)



<ComponentPreview componentName="collapsible" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/collapsible
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Add the following animations to your 

        `globals.css`

        .
      </Step>

      ```css title="globals.css" showLineNumbers
      @theme inline {
        --animate-expand: expand 0.2s ease-out;
        --animate-collapse: collapse 0.2s ease-out;

        @keyframes expand {
          from { height: var(--collapsed-height, 0); }
          to { height: var(--height); }
        }
        @keyframes collapse {
          from { height: var(--height); }
          to { height: var(--collapsed-height, 0); }
        }
      }
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/collapsible.tsx" src="/collapsible.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Collapsible
├── CollapsibleTrigger
└── CollapsibleContent
```

## Usage [#usage]

```tsx
import { 
  Collapsible, 
  CollapsibleTrigger, 
  CollapsibleContent 
} from "@/components/ui/collapsible";
```

```tsx
<Collapsible>
  <CollapsibleTrigger>Can I use this in my project?</CollapsibleTrigger>
  <CollapsibleContent>
    Yes. Free to use for personal and commercial projects. No attribution
    required.
  </CollapsibleContent>
</Collapsible>
```

## Controlled [#controlled]

Use the `open` and `onOpenChange` props to control the collapsible state programmatically.

<ComponentPreview componentName="collapsible" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

<ComponentPreview componentName="collapsible" fileName="example-disabled" />

## Examples [#examples]

### Nested [#nested]

Collapsibles can be nested to create hierarchical structures.

<ComponentPreview componentName="collapsible" fileName="example-nested" />

### Partial Collapse [#partial-collapse]

Use the `collapsedHeight` prop to show a portion of the content when collapsed.

<ComponentPreview componentName="collapsible" fileName="example-partial-collapse" />

<Alert variant="warning">
  <InfoIcon />

  <AlertTitle>
    Accessibility Notice
  </AlertTitle>

  <AlertDescription>
    Interactive elements (links, buttons, inputs) within the collapsed area automatically become inaccesible to prevent keyboard navigation to hidden content.
  </AlertDescription>
</Alert>

## API Reference [#api-reference]

### Collapsible [#collapsible]

Root component. Controls expand/collapse state and animation.

| Prop              | Type                                    | Default |
| ----------------- | --------------------------------------- | ------- |
| `open`            | `boolean`                               | `-`     |
| `defaultOpen`     | `boolean`                               | `false` |
| `onOpenChange`    | `({ open }: OpenChangeDetails) => void` | `-`     |
| `collapsedHeight` | `string`                                | `-`     |
| `className`       | `string`                                | `-`     |

### CollapsibleTrigger [#collapsibletrigger]

Toggles expand/collapse on click. Use `asChild` for custom trigger elements.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### CollapsibleContent [#collapsiblecontent]

Holds the content that expands and collapses. Animated by default.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### CollapsibleIndicator [#collapsibleindicator]

Chevron or icon that rotates to indicate open/closed state.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/collapsible#api-reference).


# Color Picker (/docs/components/color-picker)



<ComponentPreview componentName="color-picker" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/color-picker
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/color-picker.tsx" src="/color-picker.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Modes [#modes]

You can use multiple modes to build the color picker that fits your needs:

* [Input](#input) for hex or channel editing
* [Popover](#popover) for area and slider selection
* [Swatch](#swatch-picker) picker for preset colors
* [Area](#area) standalone component for color selection
* [Slider](#slider) for color adjustment

## Input [#input]

### Anatomy [#anatomy]

```text
ColorPicker
├── ColorPickerControl
│   └── InputGroup
│       ├── ColorPickerTrigger
│       │   └── ColorPickerSwatchPreview
│       └── ColorPickerInput
└── ColorPickerContent
    ├── ColorPickerArea
    │   └── ColorPickerAreaThumb
    └── ColorPickerView
        └── ColorPickerSlider
```

### Usage [#usage]

```tsx
import {
  ColorPicker,
  ColorPickerInput,
} from "@/components/ui/color-picker";
```

```tsx
<ColorPicker>
  <ColorPickerInput asChild channel="hex">
    <Input />
  </ColorPickerInput>
</ColorPicker>
```

### Controlled [#controlled]

Use the `value` and `onValueChange` props to programmatically control the color picker's state.

<ComponentPreview componentName="color-picker" fileName="example-input-controlled" />

### States [#states]

#### Invalid [#invalid]

<ComponentPreview componentName="color-picker" fileName="example-input-invalid" />

#### Disabled [#disabled]

<ComponentPreview componentName="color-picker" fileName="example-input-disabled" />

### Examples [#examples]

#### With Field [#with-field]

<ComponentPreview componentName="color-picker" fileName="example-with-field" />

#### Channel Editing [#channel-editing]

<ComponentPreview componentName="color-picker" fileName="example-input-channel" />

#### With Swatch [#with-swatch]

Input with `ColorPickerSwatchPreview` showing the current color alongside the hex input.

<ComponentPreview componentName="color-picker" fileName="example-input-with-swatch-preview" />

#### With Popover [#with-popover]

An input with trigger and popover content for area, hue, and alpha selection.

<ComponentPreview componentName="color-picker" fileName="example-input-with-popover" />

#### Compact [#compact]

Inspired by Figma's color input.

<ComponentPreview componentName="color-picker" fileName="example-input-compact" />

## Popover [#popover]

Color picker with trigger and popover content.

### Anatomy [#anatomy-1]

```text
ColorPicker
├── ColorPickerControl
│   └── ColorPickerTrigger
└── ColorPickerContent
    ├── ColorPickerArea
    │   └── ColorPickerAreaThumb
    ├── ColorPickerView
    │   ├── ColorPickerEyeDropperTrigger
    │   └── ColorPickerSlider
    │       └── ColorPickerTransparencyGrid
    └── ColorPickerSwatchGroup
        └── ColorPickerSwatchTrigger
            └── ColorPickerSwatch
```

### Usage [#usage-1]

```tsx
import {
  ColorPicker,
  ColorPickerArea,
  ColorPickerAreaThumb,
  ColorPickerContent,
  ColorPickerEyeDropperTrigger,
  ColorPickerSlider,
  ColorPickerTrigger,
  ColorPickerTransparencyGrid,
  ColorPickerView,
} from "@/components/ui/color-picker";
```

```tsx
<ColorPicker>
  <ColorPickerTrigger />
  <ColorPickerContent>
    <ColorPickerArea>
      <ColorPickerAreaThumb />
    </ColorPickerArea>
    <ColorPickerView>
      <ColorPickerEyeDropperTrigger />
      <ColorPickerSlider channel="hue" />
      <ColorPickerSlider channel="alpha">
        <ColorPickerTransparencyGrid />
      </ColorPickerSlider>
    </ColorPickerView>
  </ColorPickerContent>
</ColorPicker>
```

### States [#states-1]

#### Disabled [#disabled-1]

Set `disabled` to prevent user interaction.

<ComponentPreview componentName="color-picker" fileName="example-popover-disabled" />

### Examples [#examples-1]

#### With Eye Dropper [#with-eye-dropper]

<ComponentPreview componentName="color-picker" fileName="example-default" />

#### With Channel Editing [#with-channel-editing]

Popover with area, sliders, and input fields for editing red, green, and blue values.

<ComponentPreview componentName="color-picker" fileName="example-popover-with-channel-editing" />

#### With Only Sliders [#with-only-sliders]

Popover with hue, saturation, lightness, and alpha sliders only, no color area.

<ComponentPreview componentName="color-picker" fileName="example-popover-sliders-only" />

#### With Swatch Picker [#with-swatch-picker]

Popover with preset color swatches for quick selection.

<ComponentPreview componentName="color-picker" fileName="example-popover-with-swatch-picker" />

## Color Swatch Picker [#color-swatch-picker]

Set `inline` on `ColorPicker` so swatches render without a popover.

### Anatomy [#anatomy-2]

```text
ColorPicker
└── ColorPickerSwatchGroup
    └── ColorPickerSwatchTrigger
        └── ColorPickerSwatch
            └── ColorPickerSwatchIndicator
```

### Usage [#usage-2]

```tsx
import {
  ColorPicker,
  ColorPickerSwatchTrigger,
  ColorPickerSwatchGroup,
  ColorPickerSwatch,
  ColorPickerSwatchIndicator,
} from "@/components/ui/color-picker";
```

```tsx
<ColorPicker>
  <ColorPickerSwatchGroup>
    <ColorPickerSwatchTrigger value="#0485F7">
      <ColorPickerSwatch value="#0485F7">
          <ColorPickerSwatchIndicator />
      </ColorPickerSwatch>
    </ColorPickerSwatchTrigger>
  </ColorPickerSwatchGroup>
</ColorPicker>
```

### Controlled [#controlled-1]

Use the `value` and `onValueChange` props to programmatically control the swatch picker's state.

<ComponentPreview componentName="color-picker" fileName="example-swatch-picker-controlled" />

### States [#states-2]

#### Disabled [#disabled-2]

Set `disabled` to prevent user interaction.

<ComponentPreview componentName="color-picker" fileName="example-swatch-picker-disabled" />

### Examples [#examples-2]

#### Custom Size [#custom-size]

Customize swatch size using the `size-*` on `ColorPickerSwatchTrigger`.

<ComponentPreview componentName="color-picker" fileName="example-swatch-picker-custom-size" />

#### Custom Radius [#custom-radius]

Override the default rounded style on `ColorPickerSwatchTrigger` using the `rounded-*` utility class.

<ComponentPreview componentName="color-picker" fileName="example-swatch-picker-custom-radius" />

#### Custom Indicator [#custom-indicator]

Replace the default check icon with a custom indicator via the children of `ColorPickerSwatchIndicator`.

<ComponentPreview componentName="color-picker" fileName="example-swatch-picker-custom-indicator" />

## Area [#area]

Set `inline` on `ColorPicker` for a standalone color area.

### Anatomy [#anatomy-3]

```text
ColorPicker
└── ColorPickerArea
    └── ColorPickerAreaThumb
```

### Usage [#usage-3]

```tsx
import {
  ColorPicker,
  ColorPickerArea,
  ColorPickerAreaThumb,
} from "@/components/ui/color-picker";
```

```tsx
<ColorPicker>
  <ColorPickerArea>
    <ColorPickerAreaThumb />
  </ColorPickerArea>
</ColorPicker>
```

### Examples [#examples-3]

#### Color Channels [#color-channels]

<ComponentPreview componentName="color-picker" fileName="example-area-channels" />

#### With Dots [#with-dots]

<ComponentPreview componentName="color-picker" fileName="example-area-dots" />

## Slider [#slider]

Set `inline` on `ColorPicker` for standalone sliders. Wrap multiple sliders in `ColorPickerView`.

### Anatomy [#anatomy-4]

```text
ColorPicker
└── ColorPickerView
    └── ColorPickerSlider
        └── ColorPickerTransparencyGrid
```

### Usage [#usage-4]

```tsx
import {
  ColorPicker,
  ColorPickerSlider,
} from "@/components/ui/color-picker";
```

```tsx
<ColorPicker>
  <ColorPickerSlider channel="hue" />
</ColorPicker>
```

### Controlled [#controlled-2]

<ComponentPreview componentName="color-picker" fileName="example-slider-controlled" />

### States [#states-3]

#### Disabled [#disabled-3]

<ComponentPreview componentName="color-picker" fileName="example-slider-disabled" />

### Examples [#examples-4]

#### Alpha Channel [#alpha-channel]

<ComponentPreview componentName="color-picker" fileName="example-slider-alpha-channel" />

#### HSL Channels [#hsl-channels]

<ComponentPreview componentName="color-picker" fileName="example-slider-hsl-channels" />

#### HSBA Channels [#hsba-channels]

<ComponentPreview componentName="color-picker" fileName="example-slider-hsba-channels" />

#### RGB Channels [#rgb-channels]

<ComponentPreview componentName="color-picker" fileName="example-slider-rgb-channels" />

#### Vertical [#vertical]

<ComponentPreview componentName="color-picker" fileName="example-slider-vertical" />

### Custom spacing [#custom-spacing]

Use `[--space:--spacing("value")]` on `ColorPickerContent` to adjust internal spacing.

Default spacing is `--spacing(3)`.

<ComponentPreview componentName="color-picker" fileName="example-custom-spacing" />

> You can use breakpoint utilities to change the internal spacing at different screen sizes.

```css
  md:[--space:--spacing(6)] lg:[--space:--spacing(8)]
```

## API Reference [#api-reference]

### ColorPicker [#colorpicker]

Root element of the color picker.

| Prop            | Type                                                                                  | Default                      |
| --------------- | ------------------------------------------------------------------------------------- | ---------------------------- |
| `value`         | `string`                                                                              | -                            |
| `defaultValue`  | `string`                                                                              | -                            |
| `onValueChange` | `(details: ColorPickerValueChangeDetails) => void`                                    | -                            |
| `disabled`      | `boolean`                                                                             | `false`                      |
| `format`        | `"hex" \| "hexa" \| "rgb" \| "rgba" \| "hsl" \| "hsla" \| "hsb" \| "hsba" \| "oklch"` | -                            |
| `inline`        | `boolean`                                                                             | `false`                      |
| `positioning`   | `PositioningOptions`                                                                  | `{ placement: "top-start" }` |
| `lazyMount`     | `boolean`                                                                             | `true`                       |
| `unmountOnExit` | `boolean`                                                                             | `true`                       |
| `className`     | `string`                                                                              | -                            |

### ColorPickerTrigger [#colorpickertrigger]

Button or element that opens the color picker popover.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### ColorPickerContent [#colorpickercontent]

Holds the color picker popover. Displayed in a portal.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

| Attribute | Default        |
| --------- | -------------- |
| `--space` | `--spacing(3)` |

### ColorPickerControl [#colorpickercontrol]

Container for grouping control elements such as area, sliders, and inputs.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### ColorPickerView [#colorpickerview]

Container for sliders and inputs. Can specify `format` for child value display.

| Prop        | Type                                                                                  | Default |
| ----------- | ------------------------------------------------------------------------------------- | ------- |
| `format`    | `"hex" \| "hexa" \| "rgb" \| "rgba" \| "hsl" \| "hsla" \| "hsb" \| "hsba" \| "oklch"` | -       |
| `className` | `string`                                                                              | -       |

### ColorPickerArea [#colorpickerarea]

Two-dimensional color selection area.

| Prop        | Type                                                                                            | Default |
| ----------- | ----------------------------------------------------------------------------------------------- | ------- |
| `showDots`  | `boolean`                                                                                       | `false` |
| `xChannel`  | `"hue" \| "saturation" \| "brightness" \| "lightness" \| "red" \| "green" \| "blue" \| "alpha"` | -       |
| `yChannel`  | `"hue" \| "saturation" \| "brightness" \| "lightness" \| "red" \| "green" \| "blue" \| "alpha"` | -       |
| `className` | `string`                                                                                        | -       |

### ColorPickerAreaThumb [#colorpickerareathumb]

Draggable thumb within the color area.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### ColorPickerSlider [#colorpickerslider]

Slider for adjusting a color channel.

| Prop          | Type                                                                                                               | Default        |
| ------------- | ------------------------------------------------------------------------------------------------------------------ | -------------- |
| `channel`     | `"hex" \| "hexa" \| "red" \| "green" \| "blue" \| "hue" \| "saturation" \| "brightness" \| "lightness" \| "alpha"` | -              |
| `orientation` | `"horizontal" \| "vertical"`                                                                                       | `"horizontal"` |
| `className`   | `string`                                                                                                           | -              |

### ColorPickerTransparencyGrid [#colorpickertransparencygrid]

Checkerboard pattern for transparency. Shown as child of `ColorPickerSlider` when editing alpha.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### ColorPickerEyeDropperTrigger [#colorpickereyedroppertrigger]

Button that activates the native Eye Dropper API to sample colors from the screen.

| Prop        | Type                     | Default     |
| ----------- | ------------------------ | ----------- |
| `variant`   | `ButtonProps["variant"]` | `"outline"` |
| `size`      | `ButtonProps["size"]`    | `"icon-md"` |
| `children`  | `ReactNode`              | `Pipette`   |
| `className` | `string`                 | -           |

### ColorPickerInput [#colorpickerinput]

Input for displaying and editing a color channel value. Use `asChild` with a custom input.

| Prop      | Type                                                                                                               | Default |
| --------- | ------------------------------------------------------------------------------------------------------------------ | ------- |
| `channel` | `"hex" \| "hexa" \| "red" \| "green" \| "blue" \| "hue" \| "saturation" \| "brightness" \| "lightness" \| "alpha"` | `"hex"` |
| `asChild` | `boolean`                                                                                                          | `false` |

### ColorPickerSwatchPreview [#colorpickerswatchpreview]

Compact swatch that displays the current color. Use inside an input group for input mode.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### ColorPickerSwatchGroup [#colorpickerswatchgroup]

Container for swatch triggers in swatch picker mode.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### ColorPickerSwatchTrigger [#colorpickerswatchtrigger]

Button that selects a color when clicked. Wraps `ColorPickerSwatch` and optionally `ColorPickerSwatchIndicator`.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `value`     | `string` | -       |
| `className` | `string` | -       |

### ColorPickerSwatch [#colorpickerswatch]

Color swatch display. Use as a child of `ColorPickerSwatchTrigger`.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `value`     | `string` | -       |
| `className` | `string` | -       |

### ColorPickerSwatchIndicator [#colorpickerswatchindicator]

Check mark or custom icon shown when a swatch is selected. Pass children to customize.

| Prop        | Type        | Default     |
| ----------- | ----------- | ----------- |
| `children`  | `ReactNode` | `CheckIcon` |
| `className` | `string`    | -           |

### ColorPickerValue [#colorpickervalue]

Displays the current color as formatted text.

| Prop        | Type                                                                                  | Default |
| ----------- | ------------------------------------------------------------------------------------- | ------- |
| `format`    | `"hex" \| "hexa" \| "rgb" \| "rgba" \| "hsl" \| "hsla" \| "hsb" \| "hsba" \| "oklch"` | -       |
| `className` | `string`                                                                              | -       |

### ColorPickerValueSwatch [#colorpickervalueswatch]

Displays the current color as a swatch. Use for standalone value preview.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### parseColor [#parsecolor]

Exported utility to parse color strings. Use for programmatic color handling.

***

For the complete list of props and additional subcomponents, see the [Ark UI Color Picker documentation](https://ark-ui.com/docs/components/color-picker#api-reference).


# Combobox (/docs/components/combobox)



<ComponentPreview componentName="combobox" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/combobox
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        , 

        [Input](/docs/components/input)

        , and 

        [Input Group](/docs/components/input-group)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/combobox.tsx" src="/combobox.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Combobox
  ├── ComboboxInput
  └── ComboboxContent
      ├── ComboboxEmpty
      └── ComboboxList
        └── ComboboxGroup
          ├── ComboboxGroupLabel
          └── ComboboxItem
```

## Usage [#usage]

```tsx
import { useFilter, useListCollection } from "@ark-ui/react";
import {
  Combobox,
  ComboboxContent,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox";
```

```tsx
const { contains } = useFilter({ sensitivity: "base" });
const { collection, filter } = useListCollection({
  initialItems: [
    { label: "Apple", value: "apple" },
    { label: "Banana", value: "banana" },
  ],
  filter: contains,
});

<Combobox
  collection={collection}
  onInputValueChange={({ inputValue }) => filter(inputValue)}
>
  <ComboboxInput placeholder="Select an option" />
  <ComboboxContent>
    <ComboboxList>
      {items.map((item) => (
        <ComboboxItem item={item} key={item.value}>
          {item.label}
        </ComboboxItem>
      ))}
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

## Controlled [#controlled]

Control the selected value with `inputValue` and `onValueChange` props.

<ComponentPreview componentName="combobox" fileName="example-controlled" />

## Size [#size]

### Small [#small]

<ComponentPreview componentName="combobox" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="combobox" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="combobox" fileName="example-size-lg" />

## States [#states]

### Invalid [#invalid]

<ComponentPreview componentName="combobox" fileName="example-invalid" />

### Disabled [#disabled]

<ComponentPreview componentName="combobox" fileName="example-disabled" />

## Examples [#examples]

### Auto highlight [#auto-highlight]

Automatically highlight the first matching item as the user types.

<ComponentPreview componentName="combobox" fileName="example-autohighlight" />

### Group [#group]

<ComponentPreview componentName="combobox" fileName="example-group" />

### With Field [#with-field]

Use Combobox with `Field` components to style the combobox with the field components.

<ComponentPreview componentName="combobox" fileName="example-with-field" />

### With scroll [#with-scroll]

<ComponentPreview componentName="combobox" fileName="example-with-scroll" />

### Multiple [#multiple]

Enable multiple selection by setting the `multiple` prop to `Combobox`.

<ComponentPreview componentName="combobox" fileName="example-multiple" />

### With clear button [#with-clear-button]

Pass `showClear` to `ComboboxInput` to show a clear button.

<ComponentPreview componentName="combobox" fileName="example-with-clear-button" />

### With start icon [#with-start-icon]

<ComponentPreview componentName="combobox" fileName="example-with-start-icon" />

## API Reference [#api-reference]

### Combobox [#combobox]

Root component.

| Prop                 | Type                                         | Default      |
| -------------------- | -------------------------------------------- | ------------ |
| `collection`         | `ListCollection<T>`                          | **required** |
| `value`              | `string \| string[]`                         | -            |
| `defaultValue`       | `string \| string[]`                         | -            |
| `onValueChange`      | `(details: ValueChangeDetails<T>) => void`   | -            |
| `onInputValueChange` | `(details: InputValueChangeDetails) => void` | -            |
| `multiple`           | `boolean`                                    | `false`      |
| `disabled`           | `boolean`                                    | -            |
| `openOnClick`        | `boolean`                                    | `true`       |
| `lazyMount`          | `boolean`                                    | `true`       |
| `unmountOnExit`      | `boolean`                                    | `true`       |
| `className`          | `string`                                     | -            |

### ComboboxControl [#comboboxcontrol]

Optional wrapper for custom layouts.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### ComboboxInput [#comboboxinput]

Input with dropdown trigger and optional clear button. Combines search and selection.

| Prop          | Type                   | Default |
| ------------- | ---------------------- | ------- |
| `size`        | `"sm" \| "md" \| "lg"` | `"md"`  |
| `showTrigger` | `boolean`              | `true`  |
| `showClear`   | `boolean`              | `false` |
| `disabled`    | `boolean`              | -       |
| `className`   | `string`               | -       |

### ComboboxTrigger [#comboboxtrigger]

Opens the dropdown on click.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### ComboboxClear [#comboboxclear]

Button to clear the input value.

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | -       |

### ComboboxContent [#comboboxcontent]

Holds the dropdown options. Displayed in a portal.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### ComboboxList [#comboboxlist]

Wraps the list of options. Use with collection.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### ComboboxItem [#comboboxitem]

A single selectable option.

| Prop        | Type      | Default      |
| ----------- | --------- | ------------ |
| `item`      | `T`       | **required** |
| `className` | `string`  | -            |
| `asChild`   | `boolean` | -            |

### ComboboxGroup [#comboboxgroup]

Groups related options under an optional heading.

| Prop        | Type                  | Default |
| ----------- | --------------------- | ------- |
| `heading`   | `string \| ReactNode` | -       |
| `className` | `string`              | -       |
| `asChild`   | `boolean`             | -       |

### ComboboxGroupLabel [#comboboxgrouplabel]

Label for an option group.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### ComboboxEmpty [#comboboxempty]

Shown when no options match the current filter. Use for empty state.

| Prop        | Type        | Default             |
| ----------- | ----------- | ------------------- |
| `className` | `string`    | -                   |
| `children`  | `ReactNode` | `No results found.` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/combobox#api-reference).


# Command (/docs/components/command)



<ComponentPreview componentName="command" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/command
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Combobox](/docs/components/combobox)

        , 

        [Dialog](/docs/components/dialog)

        , 

        [Input](/docs/components/input)

        , 

        [Input Group](/docs/components/input-group)

        , 

        [Menu](/docs/components/menu)

        , and 

        [Separator](/docs/components/separator)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/command.tsx" src="/command.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Command
├── CommandInput
├── CommandList
│   ├── CommandEmpty
│   └── CommandGroup
│       ├── CommandGroupLabel
│       └── CommandItem
├── CommandSeparator
├── CommandShortcut
└── CommandFooter
```

## Usage [#usage]

```tsx
import { useFilter, useListCollection } from "@ark-ui/react";
import {
  Command,
  CommandContent,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
} from "@/components/ui/command";
```

```tsx
const { contains } = useFilter({ sensitivity: "base" });
const { collection, filter } = useListCollection({
  initialItems: [
    { label: "Search", value: "search", group: "Actions" },
    { label: "Settings", value: "settings", group: "Actions" },
  ],
  filter: contains,
  groupBy: (item) => item.group, // optional
});

<Command
  collection={collection}
  onInputValueChange={({ inputValue }) => filter(inputValue)}
>
  <CommandInput placeholder="Search..." />
  <CommandContent>
    <CommandEmpty />
    <CommandList>
      {collection.group().map(([group, items]) => (
        <CommandGroup heading={group} key={group}>
          {items.map((item) => (
            <CommandItem item={item} key={item.value}>
              {item.label}
            </CommandItem>
          ))}
        </CommandGroup>
      ))}
    </CommandList>
  </CommandContent>
</Command>
```

## Examples [#examples]

### With Dialog [#with-dialog]

<ComponentPreview componentName="command" fileName="example-dialog" />

### Groups [#groups]

Group related items with `CommandGroup` and the `heading` prop.

<ComponentPreview componentName="command" fileName="example-groups" />

### Shortcuts [#shortcuts]

Display keyboard shortcuts next to items with `CommandShortcut`.

<ComponentPreview componentName="command" fileName="example-shortcuts" />

### With Footer [#with-footer]

Add hints or actions in the footer with `CommandFooter`.

<ComponentPreview componentName="command" fileName="example-with-footer" />

### Scrollable [#scrollable]

Scrollable command menu with multiple items.

<ComponentPreview componentName="command" fileName="example-scrollable" />

## API Reference [#api-reference]

### Command [#command]

Root component.

| Prop                 | Type                                         | Default      |
| -------------------- | -------------------------------------------- | ------------ |
| `collection`         | `ListCollection<T>`                          | **required** |
| `value`              | `string \| string[]`                         | -            |
| `defaultValue`       | `string \| string[]`                         | -            |
| `onValueChange`      | `(details: ValueChangeDetails<T>) => void`   | -            |
| `onInputValueChange` | `(details: InputValueChangeDetails) => void` | -            |
| `disabled`           | `boolean`                                    | -            |
| `lazyMount`          | `boolean`                                    | `true`       |
| `unmountOnExit`      | `boolean`                                    | `true`       |
| `className`          | `string`                                     | -            |

### CommandDialog [#commanddialog]

Dialog root for the command palette. Same as `Dialog`.

| Prop           | Type                                    | Default |
| -------------- | --------------------------------------- | ------- |
| `open`         | `boolean`                               | -       |
| `defaultOpen`  | `boolean`                               | `false` |
| `onOpenChange` | `({ open }: OpenChangeDetails) => void` | -       |
| `className`    | `string`                                | -       |

### CommandDialogTrigger [#commanddialogtrigger]

Opens the command palette on click. Same as `DialogTrigger`.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | -       |

### CommandDialogContent [#commanddialogcontent]

Container for the command palette inside the dialog.

| Prop          | Type                                           | Default                            |
| ------------- | ---------------------------------------------- | ---------------------------------- |
| `size`        | `"sm" \| "md" \| "lg" \| "xl" \| "fullscreen"` | `"lg"`                             |
| `title`       | `string`                                       | `"Command Palette"`                |
| `description` | `string`                                       | `"Search for a command to run..."` |
| `className`   | `string`                                       | -                                  |

### CommandInput [#commandinput]

Search input with icon. Uses InputGroup for layout.

| Prop          | Type                   | Default |
| ------------- | ---------------------- | ------- |
| `size`        | `"sm" \| "md" \| "lg"` | `"md"`  |
| `placeholder` | `string`               | -       |
| `disabled`    | `boolean`              | -       |
| `className`   | `string`               | -       |

### CommandContent [#commandcontent]

Scrollable content container for the command list.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### CommandList [#commandlist]

List container for command items.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### CommandEmpty [#commandempty]

Content when no items match the filter.

| Prop        | Type        | Default             |
| ----------- | ----------- | ------------------- |
| `className` | `string`    | -                   |
| `children`  | `ReactNode` | `No results found.` |
| `asChild`   | `boolean`   | -                   |

### CommandGroup [#commandgroup]

Groups related items.

| Prop        | Type                  | Default |
| ----------- | --------------------- | ------- |
| `heading`   | `string \| ReactNode` | -       |
| `className` | `string`              | -       |
| `asChild`   | `boolean`             | -       |

### CommandGroupLabel [#commandgrouplabel]

Label for a group.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### CommandItem [#commanditem]

A single command or action in the palette.

| Prop        | Type     | Default      |
| ----------- | -------- | ------------ |
| `item`      | `T`      | **required** |
| `className` | `string` | -            |

### CommandSeparator [#commandseparator]

Visual divider between groups or items. Uses `Separator`.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### CommandShortcut [#commandshortcut]

Keyboard shortcut hint shown next to a command.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### CommandFooter [#commandfooter]

Footer area for hints, tips, or extra actions.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/command#api-reference).


# Context Menu (/docs/components/context-menu)



<Alert>
  <InfoIcon />

  <AlertDescription>
    Context Menu is built on top of the [Menu](/docs/components/menu) component. Check it out for more examples.
  </AlertDescription>
</Alert>

<ComponentPreview componentName="context-menu" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/context-menu
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Menu](/docs/components/menu)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/context-menu.tsx" src="/context-menu.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
ContextMenu
├── ContextMenuTrigger
└── ContextMenuContent
    ├── ContextMenuGroup
    ├── ContextMenuItem
    ├── ContextMenuCheckboxItem
    ├── ContextMenuRadioGroup
    │   └── ContextMenuRadioItem
    ├── ContextMenuSub
    │   ├── ContextMenuSubTrigger
    │   └── ContextMenuSubContent
    ├── ContextMenuSeparator
    └── ContextMenuShortcut
```

## Usage [#usage]

```tsx
import { 
  ContextMenu, 
  ContextMenuTrigger, 
  ContextMenuContent, 
  ContextMenuItemGroup,
  ContextMenuItemGroupLabel,
  ContextMenuItem,
} from "@/components/ui/context-menu";
```

```tsx
<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItemGroup>
      <ContextMenuItem value="action-1">Action 1</ContextMenuItem>
      <ContextMenuItem value="action-2">Action 2</ContextMenuItem>
      <ContextMenuItem value="action-3">Action 3</ContextMenuItem>
    </ContextMenuItemGroup>
  </ContextMenuContent>
</ContextMenu>
```

## API Reference [#api-reference]

### ContextTrigger [#contexttrigger]

Trigger component for the context menu.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

***

For a complete list of props, see the [Menu API Reference](/docs/components/menu#api-reference).


# Data List (/docs/components/data-list)



<ComponentPreview componentName="data-list" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/data-list
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/data-list.tsx" src="/data-list.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
DataList
└── DataListItem
    ├── DataListItemLabel
    └── DataListItemValue
```

## Usage [#usage]

```tsx
import {
  DataList,
  DataListItem,
  DataListItemLabel,
  DataListItemValue,
} from "@/components/ui/data-list";
```

```tsx
<DataList>
  <DataListItem>
    <DataListItemLabel>Name</DataListItemLabel>
    <DataListItemValue>John Doe</DataListItemValue>
  </DataListItem>
  <DataListItem>
    <DataListItemLabel>Email</DataListItemLabel>
    <DataListItemValue>john@example.com</DataListItemValue>
  </DataListItem>
</DataList>
```

## Orientation [#orientation]

Use the `orientation` prop to change the orientation of the datalist component.

### Horizontal [#horizontal]

<ComponentPreview componentName="data-list" fileName="example-orientation-horizontal" />

### Vertical [#vertical]

<ComponentPreview componentName="data-list" fileName="example-orientation-vertical" />

## Examples [#examples]

### Info Tip [#info-tip]

<ComponentPreview componentName="data-list" fileName="example-info-tip" />

### Separator [#separator]

Use the `divide-y` utility class on `DataList` to add a separator between items.

<ComponentPreview componentName="data-list" fileName="example-separator" />

## API Reference [#api-reference]

### DataList [#datalist]

Root wrapper for label-value list layout.

| Prop          | Type                         | Default        |
| ------------- | ---------------------------- | -------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
| `className`   | `string`                     | -              |
| `asChild`     | `boolean`                    | `false`        |

### DataListItem [#datalistitem]

Single label-value row.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### DataListItemLabel [#datalistitemlabel]

Label or key for the row.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### DataListItemValue [#datalistitemvalue]

Value or content for the row.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |


# Date Picker (/docs/components/date-picker)



<ComponentPreview componentName="date-picker" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/date-picker
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        , 

        [Calendar](/docs/components/calendar)

        , 

        [Input](/docs/components/input)

        , and 

        [Input Group](/docs/components/input-group)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/date-picker.tsx" src="/date-picker.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
DatePicker
├── DatePickerTrigger
└── DatePickerContent
    ── (Calendar components)
```

## Usage [#usage]

```tsx
import {
  DatePicker,
  DatePickerCalendar,
  DatePickerClearTrigger,
  DatePickerContent,
  DatePickerControl,
  DatePickerInput,
  DatePickerLabel,
  DatePickerPositioner,
  DatePickerTrigger,
} from "@/components/ui/date-picker";
```

```tsx
<DatePicker selectionMode="single">
  <DatePickerLabel>Pick a date</DatePickerLabel>
  <DatePickerControl>
    <DatePickerInput index={0} placeholder="Select date" />
    <DatePickerTrigger />
    <DatePickerClearTrigger asChild>
      <Button size="sm" variant="outline">Clear</Button>
    </DatePickerClearTrigger>
  </DatePickerControl>
  <DatePickerPositioner>
    <DatePickerContent>
      <DatePickerCalendar />
    </DatePickerContent>
  </DatePickerPositioner>
</DatePicker>
```

## Examples [#examples]

### Input [#input]

Use `DatePickerInput` for a text input with calendar icon that opens the date picker.

<ComponentPreview componentName="date-picker" fileName="example-input" />

### Range [#range]

Select a date range with `selectionMode="range"`.

<ComponentPreview componentName="date-picker" fileName="example-range" />

### Time [#time]

Use `DatePickerTimer` for time selection.

<ComponentPreview componentName="date-picker" fileName="example-time" />

### With Presets [#with-presets]

Add quick single-date presets in a side panel.

<ComponentPreview componentName="date-picker" fileName="example-with-presets" />

### Custom format [#custom-format]

Customize the format of the presets using external date formatting library like `date-fns`.

<ComponentPreview componentName="date-picker" fileName="example-custom-format" />

## API Reference [#api-reference]

### DatePicker [#datepicker]

Root element. Extends [Calendar](/docs/components/calendar#api-reference).

| Prop            | Type                                    | Default                |
| --------------- | --------------------------------------- | ---------------------- |
| `value`         | `DateValue[]`                           | -                      |
| `defaultValue`  | `DateValue[]`                           | -                      |
| `onValueChange` | `(details: ValueChangeDetails) => void` | -                      |
| `selectionMode` | `"single" \| "range" \| "multiple"`     | `"single"`             |
| `positioning`   | `PositioningOptions`                    | `{ placement: "top" }` |
| `lazyMount`     | `boolean`                               | -                      |
| `unmountOnExit` | `boolean`                               | -                      |

### DatePickerTrigger [#datepickertrigger]

Button that opens the date picker. `button`

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | -       |

### DatePickerInput [#datepickerinput]

Input with calendar icon that opens the date picker on click. `input`

| Prop          | Type                   | Default |
| ------------- | ---------------------- | ------- |
| `placeholder` | `string`               | -       |
| `index`       | `number`               | -       |
| `size`        | `"sm" \| "md" \| "lg"` | -       |
| `className`   | `string`               | -       |

### DatePickerContent [#datepickercontent]

Wraps the calendar. Inherits `--cell-size` from calendar for date cell sizing.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

| Attribute     | Default        |
| ------------- | -------------- |
| `--cell-size` | `--spacing(8)` |

### DatePickerValue [#datepickervalue]

Displays the selected date(s) as text. Use inside `DatePickerTrigger`. `span`

| Prop          | Type      | Default |
| ------------- | --------- | ------- |
| `placeholder` | `string`  | -       |
| `className`   | `string`  | -       |
| `asChild`     | `boolean` | -       |

### DatePickerTimer [#datepickertimer]

Time input for selecting hour and minute. Use alongside the calendar for date-time selection. `input`

| Prop            | Type                                    | Default |
| --------------- | --------------------------------------- | ------- |
| `value`         | `string`                                | -       |
| `defaultValue`  | `string`                                | -       |
| `onValueChange` | `(details: ValueChangeDetails) => void` | -       |
| `className`     | `string`                                | -       |

### DatePickerPresetTrigger [#datepickerpresettrigger]

Quick preset button for dates. `button`

| Prop        | Type          | Default |
| ----------- | ------------- | ------- |
| `className` | `string`      | -       |
| `value`     | `DateValue[]` | -       |
| `asChild`   | `boolean`     | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/date-picker#api-reference).


# Dialog (/docs/components/dialog)



<ComponentPreview componentName="dialog" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/dialog
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

         and 

        [Scroll Area](/docs/components/scroll-area)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/dialog.tsx" src="/dialog.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Dialog
├── DialogTrigger
└── DialogContent
    ├── DialogHeader
    │   ├── DialogTitle
    │   └── DialogDescription
    ├── DialogBody
    └── DialogFooter
        └── DialogClose
```

## Usage [#usage]

```tsx
import { 
  Dialog, 
  DialogTrigger, 
  DialogContent, 
  DialogHeader,
  DialogTitle, 
  DialogDescription, 
  DialogBody,
  DialogFooter,
  DialogClose,
} from "@/components/ui/dialog";
```

```tsx
<Dialog>
  <DialogTrigger />
  <DialogContent>
    <DialogHeader>
      <DialogTitle />
      <DialogDescription />
    </DialogHeader>
    <DialogBody>
      {/** your content here */}
    </DialogBody>
    <DialogFooter>
      <DialogClose />
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Title & Description [#title--description]

`DialogHeader` supports two usage patterns:

### Using props [#using-props]

Pass `title` and `description` props directly to `DialogHeader`.

```tsx showLineNumbers
<DialogHeader title="Dialog Title" description="Dialog description" />
```

> This approach does not require `DialogTitle` or `DialogDescription` components.

### Using components [#using-components]

Use `DialogTitle` and `DialogDescription` as children for more control.

```tsx showLineNumbers
<DialogHeader>
  <DialogTitle>Dialog Title</DialogTitle>
  <DialogDescription>Dialog description</DialogDescription>
</DialogHeader>
```

## Examples [#examples]

### With Scroll [#with-scroll]

Use `DialogBody` to make the content area scrollable while keeping header and footer fixed.

<ComponentPreview componentName="dialog" fileName="example-scroll-area" />

### No Close Button [#no-close-button]

Use the `showCloseButton` prop to hide the close button in the top right corner.

<ComponentPreview componentName="dialog" fileName="example-no-close-button" />

### Close behavior [#close-behavior]

Use `closeOnInteractOutside` and `closeOnEscape` props to prevent closing on outside click and escape.

<ComponentPreview componentName="dialog" fileName="example-close-behavior" />

### Open from Menu [#open-from-menu]

Open a dialog imperatively from a menu item using the `onSelect` handler.

<ComponentPreview componentName="dialog" fileName="example-open-from-menu" />

### Non-Modal [#non-modal]

Use `modal={false}` to allow interaction with elements outside the dialog. Disables focus trapping and scroll prevention.

<ComponentPreview componentName="dialog" fileName="example-non-modal" />

### Initial Focus [#initial-focus]

Use `initialFocusEl` to control which element receives focus when the dialog opens.

<ComponentPreview componentName="dialog" fileName="example-initial-focus" />

### Nested [#nested]

Nest dialogs within one another.

<ComponentPreview componentName="dialog" fileName="example-nested" />

### Custom spacing [#custom-spacing]

Use `[--space:--spacing("value")]` on `DialogContent` to adjust internal padding.

Default spacing is `--spacing(6)`.

<ComponentPreview componentName="dialog" fileName="example-custom-spacing" />

> You can use breakpoint utilities to change the internal spacing at different screen sizes.

```css
  md:[--space:--spacing(6)] lg:[--space:--spacing(8)]
```

## API Reference [#api-reference]

### Dialog [#dialog]

Root context provider. Controls open state and modal behavior.

| Prop                     | Type                                    | Default |
| ------------------------ | --------------------------------------- | ------- |
| `open`                   | `boolean`                               | `-`     |
| `defaultOpen`            | `boolean`                               | `false` |
| `onOpenChange`           | `({ open }: OpenChangeDetails) => void` | `-`     |
| `modal`                  | `boolean`                               | `true`  |
| `closeOnEscape`          | `boolean`                               | `true`  |
| `closeOnInteractOutside` | `boolean`                               | `true`  |
| `initialFocusEl`         | `() => MaybeElement`                    | `-`     |
| `finalFocusEl`           | `() => MaybeElement`                    | `-`     |
| `onEscapeKeyDown`        | `(event: KeyboardEvent) => void`        | `-`     |
| `onInteractOutside`      | `(event: InteractOutsideEvent) => void` | `-`     |
| `className`              | `string`                                | `-`     |

### DialogTrigger [#dialogtrigger]

Opens the dialog on click. Use `asChild` for custom trigger elements.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

### DialogContent [#dialogcontent]

Holds the dialog panel. Supports size variants from sm to fullscreen.

| Prop              | Type                                           | Default |
| ----------------- | ---------------------------------------------- | ------- |
| `size`            | `"sm" \| "md" \| "lg" \| "xl" \| "fullscreen"` | `"md"`  |
| `showCloseButton` | `boolean`                                      | `true`  |
| `className`       | `string`                                       | `-`     |

| Attribute | Default        |
| --------- | -------------- |
| `--space` | `--spacing(6)` |

### DialogHeader [#dialogheader]

Header area for title and description. Accepts props or children.

| Prop          | Type     | Default |
| ------------- | -------- | ------- |
| `title`       | `string` | `-`     |
| `description` | `string` | `-`     |
| `className`   | `string` | `-`     |

### DialogBody [#dialogbody]

Scrollable body content. Uses [ScrollArea](/docs/components/scroll-area) for overflow.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### DialogFooter [#dialogfooter]

Footer area for action buttons.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### DialogTitle [#dialogtitle]

Accessible title for the dialog. Announced to screen readers.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

### DialogDescription [#dialogdescription]

Accessible description for the dialog. Announced to screen readers.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

### DialogClose [#dialogclose]

Closes the dialog on click. Use `asChild` for custom close elements.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

### DialogOverlay [#dialogoverlay]

Dimmed overlay behind the dialog panel.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/dialog#api-reference).


# Drawer (/docs/components/drawer)



<ComponentPreview componentName="drawer" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/drawer
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Scroll Area](/docs/components/scroll-area)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/drawer.tsx" src="/drawer.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Drawer
├── DrawerTrigger
└── DrawerContent
    ├── DrawerGrabber
    ├── DrawerContentInner
    │   ├── DrawerHeader
    │   └── DrawerBody
    └── DrawerFooter
        └── DrawerClose
```

## Usage [#usage]

```tsx
import {
  Drawer,
  DrawerTrigger,
  DrawerContent,
  DrawerContentInner,
  DrawerHeader,
  DrawerTitle,
  DrawerDescription,
  DrawerBody,
  DrawerFooter,
  DrawerClose,
} from "@/components/ui/drawer";
```

```tsx
<Drawer>
  <DrawerTrigger />
  <DrawerContent>
    <DrawerContentInner>
      <DrawerHeader>
        <DrawerTitle />
        <DrawerDescription />
      </DrawerHeader>
      <DrawerBody>
        {/** your content here */}
      </DrawerBody>
    </DrawerContentInner>
    <DrawerFooter>
      <DrawerContentInner>
        <DrawerClose />
      </DrawerContentInner>
    </DrawerFooter>
  </DrawerContent>
</Drawer>
```

## Examples [#examples]

### Container [#container]

Use `DrawerContentInner` to constrain drawer content width to `max-w-sm`.

<ComponentPreview componentName="drawer" fileName="example-drawer-content-inner" />

### Inset Variant [#inset-variant]

Use `variant="inset"` on `DrawerContent` so the drawer appears as a floating card rather than edge-to-edge.

<ComponentPreview componentName="drawer" fileName="example-inset" />

### Swipe Directions [#swipe-directions]

Control which direction the drawer slides and swipes using `swipeDirection` on the root.

<ComponentPreview componentName="drawer" fileName="example-swipe-directions" />

### Snap Points [#snap-points]

Use `snapPoints` to allow the drawer to snap to multiple heights.

<ComponentPreview componentName="drawer" fileName="example-snap-points" />

### Custom spacing [#custom-spacing]

Use `[--space:--spacing("value")]` on `DrawerContent` to adjust internal spacing.

Default spacing is `--spacing(6)`.

<ComponentPreview componentName="drawer" fileName="example-custom-spacing" />

> You can use breakpoint utilities to change the internal spacing at different screen sizes.

```css
  md:[--space:--spacing(6)] lg:[--space:--spacing(8)]
```

## API Reference [#api-reference]

### Drawer [#drawer]

Root element of the drawer.

| Prop                     | Type                                    | Default  |
| ------------------------ | --------------------------------------- | -------- |
| `open`                   | `boolean`                               | `-`      |
| `defaultOpen`            | `boolean`                               | `false`  |
| `onOpenChange`           | `({ open }: OpenChangeDetails) => void` | `-`      |
| `swipeDirection`         | `"up" \| "down" \| "left" \| "right"`   | `"down"` |
| `snapPoints`             | `(number \| string)[]`                  | `[1]`    |
| `defaultSnapPoint`       | `number \| string \| null`              | `1`      |
| `snapToSequentialPoints` | `boolean`                               | `false`  |
| `closeThreshold`         | `number`                                | `0.25`   |
| `swipeVelocityThreshold` | `number`                                | `700`    |
| `preventDragOnScroll`    | `boolean`                               | `true`   |
| `modal`                  | `boolean`                               | `true`   |
| `closeOnEscape`          | `boolean`                               | `true`   |
| `closeOnInteractOutside` | `boolean`                               | `true`   |
| `className`              | `string`                                | `-`      |

### DrawerTrigger [#drawertrigger]

Opens the drawer on click. Use `asChild` for custom trigger elements.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

### DrawerContent [#drawercontent]

Holds the drawer panel. Supports swipe-to-close; direction inherited from root `swipeDirection`.

| Prop        | Type                   | Default     |
| ----------- | ---------------------- | ----------- |
| `variant`   | `"default" \| "inset"` | `"default"` |
| `className` | `string`               | `-`         |

| Attribute | Default        |
| --------- | -------------- |
| `--bleed` | `3rem`         |
| `--space` | `--spacing(4)` |

### DrawerContentInner [#drawercontentinner]

Wrapper that constrains content to `max-w-sm` and centers it. Use to wrap the main body (header + body) or footer actions. When used inside `DrawerFooter`, inherits `flex-col-reverse` and `gap-2` for button layout.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### DrawerHeader [#drawerheader]

Header area for title and description. Accepts props or children.

| Prop          | Type     | Default |
| ------------- | -------- | ------- |
| `title`       | `string` | `-`     |
| `description` | `string` | `-`     |
| `className`   | `string` | `-`     |

### DrawerTitle [#drawertitle]

Accessible title for the drawer. Announced to screen readers.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

### DrawerDescription [#drawerdescription]

Accessible description for the drawer. Announced to screen readers.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

### DrawerBody [#drawerbody]

Scrollable body content. Uses [ScrollArea](/docs/components/scroll-area) for overflow. Supports `scrollFade` for gradient edges.

| Prop         | Type      | Default |
| ------------ | --------- | ------- |
| `scrollFade` | `boolean` | `false` |
| `className`  | `string`  | `-`     |

### DrawerFooter [#drawerfooter]

Footer area for action buttons.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### DrawerClose [#drawerclose]

Closes the drawer on click. Use `asChild` for custom close elements.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/dialog#api-reference).


# Editable (/docs/components/editable)



<ComponentPreview componentName="editable" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/editable
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/editable.tsx" src="/editable.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Editable
├── EditableArea
│   ├── EditablePreview
│   └── EditableInput
└── EditableControl
    ├── EditableEditTrigger
    ├── EditableCancelTrigger
    └── EditableSubmitTrigger
```

## Usage [#usage]

```tsx
import { 
  Editable,
  EditableArea,
  EditableInput,
  EditablePreview,
  EditableControl,
  EditableCancelTrigger,
  EditableSubmitTrigger,
  EditableEditTrigger,
} from "@/components/ui/editable";
```

```tsx
<Editable>
  <EditableArea>
    <EditableInput />
    <EditablePreview />
  </EditableArea>
  <EditableControl>
    <EditableCancelTrigger/>
    <EditableSubmitTrigger/>
    <EditableEditTrigger/>
  </EditableControl>
</Editable>
```

## Controlled [#controlled]

Make the entire form editable at once by using the `edit` prop.

The `value` and `onValueChange` props control the editable component programmatically.

<ComponentPreview componentName="editable" fileName="example-controlled" />

## Modes [#modes]

The `activationMode` prop controls how editing is triggered.

#### Focus [#focus]

Editing starts when the field receives focus.

<ComponentPreview componentName="editable" fileName="example-activation-focus" />

#### Click [#click]

Editing starts with a single click on the preview.

<ComponentPreview componentName="editable" fileName="example-activation-click" />

#### Double-Click [#double-click]

Editing starts with a double-click on the preview.

<ComponentPreview componentName="editable" fileName="example-dblclick" />

#### None [#none]

No automatic activation. Use `EditableEditTrigger` to manually start editing.

<ComponentPreview componentName="editable" fileName="example-activation-none" />

## Sizes [#sizes]

The `size` prop on `EditablePreview` controls the preview dimensions.

### Small [#small]

<ComponentPreview componentName="editable" fileName="example-size-sm" />

### Large [#large]

<ComponentPreview componentName="editable" fileName="example-size-lg" />

## Orientation [#orientation]

The `orientation` prop controls the layout of the editable component and its controls.

#### Horizontal [#horizontal]

<ComponentPreview componentName="editable" fileName="example-orientation-horizontal" />

#### Vertical [#vertical]

<ComponentPreview componentName="editable" fileName="example-orientation-vertical" />

## Examples [#examples]

### With Textarea [#with-textarea]

<ComponentPreview componentName="editable" fileName="example-with-textarea" />

### Without Controls [#without-controls]

Edit without control buttons. Press Enter to save, Escape to cancel.

<ComponentPreview componentName="editable" fileName="example-without-controls" />

## API Reference [#api-reference]

### Editable [#editable]

Root component. Manages edit mode and value.

| Prop             | Type                                 | Default        |
| ---------------- | ------------------------------------ | -------------- |
| `activationMode` | `focus \| dblclick \| click \| none` | `'focus'`      |
| `orientation`    | `"horizontal" \| "vertical"`         | `"horizontal"` |
| `submitMode`     | `both \| enter \| blur \| none`      | `'both'`       |
| `asChild`        | `boolean`                            | `-`            |
| `className`      | `string`                             | `-`            |

### EditableArea [#editablearea]

Wraps the input and preview views.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `className` | `string`  | `-`     |

### EditableInput [#editableinput]

Input shown when editing. Use `asChild` for custom input elements.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `className` | `string`  | `-`     |

### EditablePreview [#editablepreview]

Shows the value when not editing. Click to enter edit mode.

| Prop        | Type                                   | Default |
| ----------- | -------------------------------------- | ------- |
| `asChild`   | `boolean`                              | `-`     |
| `size`      | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"`  |
| `className` | `string`                               | `-`     |

### EditableControl [#editablecontrol]

Holds edit/cancel/submit control buttons.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `className` | `string`  | `-`     |

### EditableEditTrigger [#editableedittrigger]

Enters edit mode on click.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `className` | `string`  | `-`     |

### EditableCancelTrigger [#editablecanceltrigger]

Cancels editing and reverts to previous value.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | `-`     |

### EditableSubmitTrigger [#editablesubmittrigger]

Submits the edited value and exits edit mode.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | `-`     |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/editable#api-reference).


# Field (/docs/components/field)



<ComponentPreview componentName="field" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/field
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Separator](/docs/components/separator)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/field.tsx" src="/field.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
FieldSet
├── FieldLegend
└── FieldGroup
    ├── Field
    ├── FieldLabel
    │   └── FieldRequiredIndicator
    ├── FieldTitle
    ├── FieldDescription
    ├── FieldSeparator
    ├── FieldHelper
    └── FieldError
```

## Usage [#usage]

```tsx
import { 
  Field, 
  FieldLabel, 
  FieldInput, 
  FieldHelper, 
  FieldError 
} from "@/components/ui/field";
```

```tsx
<Field>
  <FieldLabel>Email</FieldLabel>
  <FieldInput />
  <FieldHelper>Enter your email address</FieldHelper>
  <FieldError>Email is required</FieldError>
</Field>
```

## Examples [#examples]

### Input [#input]

<ComponentPreview componentName="field" fileName="example-input-group" />

### Autocomplete [#autocomplete]

<ComponentPreview componentName="field" fileName="example-autocomplete-field" />

### Combobox [#combobox]

<ComponentPreview componentName="field" fileName="example-combobox-field" />

### Combobox Multiple [#combobox-multiple]

<ComponentPreview componentName="field" fileName="example-combobox-multiple-field" />

### Textarea [#textarea]

<ComponentPreview componentName="field" fileName="example-textarea-field" />

### Select [#select]

<ComponentPreview componentName="field" fileName="example-select-field" />

### Checkbox [#checkbox]

<ComponentPreview componentName="field" fileName="example-checkbox-field" />

### Checkbox Group [#checkbox-group]

<ComponentPreview componentName="field" fileName="example-checkbox-group-field" />

### Radio Group [#radio-group]

<ComponentPreview componentName="field" fileName="example-radio-group-field" />

### Switch [#switch]

<ComponentPreview componentName="field" fileName="example-switch-field" />

### Slider [#slider]

Use `SliderLabel` inside the `Slider` to label the slider.

<ComponentPreview componentName="field" fileName="example-slider-field" />

### Number Input [#number-input]

<ComponentPreview componentName="field" fileName="example-number-input" />

### Field Group [#field-group]

<ComponentPreview componentName="field" fileName="example-field-group" />

## API Reference [#api-reference]

### Field [#field]

Root layout for label, control, and helper/error text.

| Prop          | Type                                         | Default      |
| ------------- | -------------------------------------------- | ------------ |
| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` |
| `reverse`     | `boolean`                                    | `false`      |
| `invalid`     | `boolean`                                    | `-`          |
| `disabled`    | `boolean`                                    | `-`          |
| `required`    | `boolean`                                    | `-`          |
| `readOnly`    | `boolean`                                    | `-`          |
| `asChild`     | `boolean`                                    | `-`          |
| `className`   | `string`                                     | `-`          |

### FieldSet [#fieldset]

Groups related form controls semantically.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FieldLegend [#fieldlegend]

Legend or label for a FieldSet group.

| Prop        | Type                  | Default    |
| ----------- | --------------------- | ---------- |
| `variant`   | `"legend" \| "label"` | `"legend"` |
| `className` | `string`              | `-`        |

### FieldGroup [#fieldgroup]

Groups multiple fields with consistent spacing.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FieldContent [#fieldcontent]

Wraps label, description, and error. Use with horizontal orientation.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FieldLabel [#fieldlabel]

Label associated with the control.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `className` | `string`  | `-`     |

### FieldRequiredIndicator [#fieldrequiredindicator]

| Prop        | Type        | Default |
| ----------- | ----------- | ------- |
| `children`  | `ReactNode` | `"*"`   |
| `className` | `string`    | `-`     |
| `asChild`   | `boolean`   | `-`     |

### FieldTitle [#fieldtitle]

Title wrapper for grouped field content.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FieldDescription [#fielddescription]

Helper text or description. Shown in muted foreground.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FieldSeparator [#fieldseparator]

Horizontal divider between field groups. Optional center label.

| Prop        | Type        | Default |
| ----------- | ----------- | ------- |
| `children`  | `ReactNode` | `-`     |
| `className` | `string`    | `-`     |

### FieldHelper [#fieldhelper]

Alias for FieldDescription. Use for consistency with other form libraries.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FieldError [#fielderror]

Error message shown when the field is invalid. Shown in destructive color.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/field#api-reference).


# File Upload (/docs/components/file-upload)



<ComponentPreview componentName="file-upload" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/file-upload
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/file-upload.tsx" src="/file-upload.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
FileUpload
├── FileUploadTrigger
├── FileUploadDropzone
│   ├── FileUploadDropzoneIcon
│   ├── FileUploadTitle
│   ├── FileUploadDescription
│   └── FileUploadHelper
├── FileUploadItemGroup
│   └── FileUploadList
│       └── FileUploadItem
│           ├── FileUploadItemPreview
│           │   └── FileUploadItemPreviewImage
│           ├── FileUploadItemName
│           ├── FileUploadItemSize
│           └── FileUploadItemDeleteTrigger
└── FileUploadClearTrigger
```

## Usage [#usage]

```tsx
import { 
  FileUpload,
  FileUploadDropzone,
  FileUploadDropzoneIcon,
  FileUploadTitle,
  FileUploadDescription,
  FileUploadHelper,
  FileUploadTrigger,
  FileUploadList,
} from "@/components/ui/file-upload";
```

```tsx
<FileUpload maxFiles={2} accept={["image/*png,image/jpeg*", ".pdf"]}>
  <FileUploadDropzone>
    <FileUploadDropzoneIcon />
    <FileUploadTitle>Drop files here</FileUploadTitle>
    <FileUploadDescription>or</FileUploadDescription>
    <FileUploadTrigger />
    <FileUploadHelper>You can upload up to 2 files at a time.</FileUploadHelper>
  </FileUploadDropzone>
  <FileUploadList />
</FileUpload>
```

## Examples [#examples]

### Multiple Files [#multiple-files]

Use the `maxFiles` prop to allow uploading multiple files at once.

<ComponentPreview componentName="file-upload" fileName="example-multiple-files" />

### Trigger only [#trigger-only]

<ComponentPreview componentName="file-upload" fileName="example-trigger" />

### Dropzone only [#dropzone-only]

Use `FileUploadDropzone` to enable drag-and-drop. It exposes a `data-dragging` attribute for styling the drag state.

<ComponentPreview componentName="file-upload" fileName="example-dropzone" />

### Accepted Files [#accepted-files]

Use the `accept` prop to restrict file types.

<ComponentPreview componentName="file-upload" fileName="example-accepted-file-types" />

### With Field [#with-field]

Use `Field` to add helper text and error handling.

<ComponentPreview componentName="file-upload" fileName="example-with-field" />

### Custom Preview [#custom-preview]

```tsx
const { acceptedFiles } = useFileUploadContext();

return (
  <div>
    {acceptedFiles.map((file) => (
      <div key={file.name}>{file.name}</div>
    ))}
  </div>
);
```

<ComponentPreview componentName="file-upload" fileName="example-custom-preview" />

### Media Capture [#media-capture]

Use the `capture` prop to capture and upload media directly from the device camera.

<ComponentPreview componentName="file-upload" fileName="example-media-capture" />

<Alert variant="warning">
  <InfoIcon />

  <AlertTitle>
    The capture prop is only supported on mobile devices.
  </AlertTitle>
</Alert>

### Directory Upload [#directory-upload]

Use the `directory` prop to upload entire folders.

<ComponentPreview componentName="file-upload" fileName="example-directory-upload" />

<Alert variant="warning">
  <InfoIcon />

  <AlertTitle>
    Attention: Directory Upload
  </AlertTitle>

  <AlertDescription>
    When uploading directories with many files, set `maxFiles` to a higher value or remove it entirely to prevent rejections.
  </AlertDescription>
</Alert>

### Clear Trigger [#clear-trigger]

Use `FileUploadClearTrigger` to remove all uploaded files at once.

<ComponentPreview componentName="file-upload" fileName="example-clear-trigger" />

### Custom spacing [#custom-spacing]

Use `[--space:--spacing("value")]` on `FileUploadDropzone` to adjust internal spacing.

Default spacing is `--spacing(6)`.

<ComponentPreview componentName="file-upload" fileName="example-custom-spacing" />

> You can use breakpoint utilities to change the internal spacing at different screen sizes.

```css
  md:[--space:--spacing(6)] lg:[--space:--spacing(8)]
```

## API Reference [#api-reference]

### FileUpload [#fileupload]

Root component. Manages file state and wraps the upload UI.

| Prop                   | Type                                                                | Default    |
| ---------------------- | ------------------------------------------------------------------- | ---------- |
| `accept`               | `string \| Record<string, string[]> \| FileMimeType[]`              | `-`        |
| `acceptedFiles`        | `File[]`                                                            | `-`        |
| `allowDrop`            | `boolean`                                                           | `true`     |
| `capture`              | `"user" \| "environment"`                                           | `-`        |
| `defaultAcceptedFiles` | `File[]`                                                            | `-`        |
| `directory`            | `boolean`                                                           | `false`    |
| `disabled`             | `boolean`                                                           | `-`        |
| `invalid`              | `boolean`                                                           | `-`        |
| `maxFiles`             | `number`                                                            | `1`        |
| `maxFileSize`          | `number`                                                            | `Infinity` |
| `minFileSize`          | `number`                                                            | `0`        |
| `name`                 | `string`                                                            | `-`        |
| `onFileAccept`         | `(details: FileAcceptDetails) => void`                              | `-`        |
| `onFileChange`         | `(details: FileChangeDetails) => void`                              | `-`        |
| `onFileReject`         | `(details: FileRejectDetails) => void`                              | `-`        |
| `readOnly`             | `boolean`                                                           | `-`        |
| `required`             | `boolean`                                                           | `-`        |
| `transformFiles`       | `(files: File[]) => Promise<File[]>`                                | `-`        |
| `validate`             | `(file: File, details: FileValidateDetails) => FileError[] \| null` | `-`        |
| `className`            | `string`                                                            | `-`        |

### FileUploadTrigger [#fileuploadtrigger]

Opens the native file picker on click.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `className` | `string`  | `-`     |

### FileUploadDropzone [#fileuploaddropzone]

Drop zone for drag-and-drop. Exposes `data-dragging` when files are dragged over.

| Prop           | Type      | Default |
| -------------- | --------- | ------- |
| `asChild`      | `boolean` | `-`     |
| `disableClick` | `boolean` | `-`     |
| `className`    | `string`  | `-`     |

| Attribute | Default        |
| --------- | -------------- |
| `--space` | `--spacing(8)` |

### FileUploadDropzoneIcon [#fileuploaddropzoneicon]

Icon shown in the dropzone.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FileUploadTitle [#fileuploadtitle]

Title text for the dropzone.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FileUploadDescription [#fileuploaddescription]

Description or hint for the dropzone.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FileUploadHelper [#fileuploadhelper]

Small text that provides additional information about the dropzone.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FileUploadList [#fileuploadlist]

List of uploaded files. Hidden when empty.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FileUploadItemGroup [#fileuploaditemgroup]

List of uploaded files.

| Prop        | Type                       | Default |
| ----------- | -------------------------- | ------- |
| `asChild`   | `boolean`                  | `-`     |
| `type`      | `"accepted" \| "rejected"` | `-`     |
| `className` | `string`                   | `-`     |

### FileUploadItem [#fileuploaditem]

Single uploaded file with preview and remove button.

| Prop        | Type      | Default  |
| ----------- | --------- | -------- |
| `file`      | `File`    | required |
| `asChild`   | `boolean` | `-`      |
| `className` | `string`  | `-`      |

### FileUploadItemPreview [#fileuploaditempreview]

Preview container for a file.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `type`      | `string`  | `'.*'`  |
| `className` | `string`  | `-`     |

### FileUploadItemPreviewImage [#fileuploaditempreviewimage]

Image thumbnail for image files. Use inside `FileUploadItemPreview` with `type="image/*"`.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `className` | `string`  | `-`     |

### FileUploadItemName [#fileuploaditemname]

Shows the file name.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `className` | `string`  | `-`     |

### FileUploadItemSize [#fileuploaditemsize]

Shows the formatted file size.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `className` | `string`  | `-`     |

### FileUploadItemDeleteTrigger [#fileuploaditemdeletetrigger]

Removes a single file from the list.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `className` | `string`  | `-`     |

### FileUploadClearTrigger [#fileuploadcleartrigger]

Removes all files from the list.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `-`     |
| `className` | `string`  | `-`     |

### useFileUploadContext [#usefileuploadcontext]

Hook to access file upload state and methods. Use inside `FileUpload` or `FileUploadRootProvider`.

| Property             | Type                                                    |
| -------------------- | ------------------------------------------------------- |
| `acceptedFiles`      | `File[]`                                                |
| `rejectedFiles`      | `FileRejection[]`                                       |
| `openFilePicker`     | `() => void`                                            |
| `deleteFile`         | `(file: File, type?: ItemType) => void`                 |
| `clearFiles`         | `() => void`                                            |
| `clearRejectedFiles` | `() => void`                                            |
| `getFileSize`        | `(file: File) => string`                                |
| `createFileUrl`      | `(file: File, cb: (url: string) => void) => () => void` |
| `setClipboardFiles`  | `(dt: DataTransfer) => boolean`                         |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/file-upload#api-reference).


# Float (/docs/components/float)



<ComponentPreview componentName="float" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/float
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/float.tsx" src="/float.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Float } from "@/components/ui/float";
```

```tsx
<div className="relative">
  <Float placement="top-end">
    {/** floated content **/}
  </Float>
</div>
```

## Placement [#placement]

<ComponentPreview componentName="float" fileName="example-placement" />

## API Reference [#api-reference]

### Float [#float]

| Prop        | Type                                                                                                                                                 | Default     |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `placement` | `"top-start" \| "top-center" \| "top-end" \| "middle-start" \| "middle-center" \| "middle-end" \| "bottom-start" \| "bottom-center" \| "bottom-end"` | `"top-end"` |
| `className` | `string`                                                                                                                                             | -           |
| `asChild`   | `boolean`                                                                                                                                            | `false`     |


# Floating Panel (/docs/components/floating-panel)



<ComponentPreview componentName="floating-panel" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/floating-panel
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

         and 

        [Scroll Area](/docs/components/scroll-area)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/floating-panel.tsx" src="/floating-panel.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
FloatingPanel
├── FloatingPanelTrigger
└── FloatingPanelContent
    ├── FloatingPanelDragTrigger
    ├── FloatingPanelHeader
    │   ├── FloatingPanelControl
    │   │   ├── FloatingPanelMinimize
    │   │   ├── FloatingPanelMaximize
    │   │   └── FloatingPanelRestore
    │   ├── FloatingPanelTitle
    │   ├── FloatingPanelResizeTrigger
    │   ├── FloatingPanelStageTrigger
    │   └── FloatingPanelCloseTrigger
    ├── FloatingPanelBody
    └── FloatingPanelFooter
```

## Usage [#usage]

```tsx
import { 
  FloatingPanel,
  FloatingPanelTrigger,
  FloatingPanelContent,
  FloatingPanelHeader,
  FloatingPanelTitle,
  FloatingPanelBody,
} from "@/components/ui/floating-panel";
```

```tsx
<FloatingPanel>
  <FloatingPanelTrigger />
  <FloatingPanelContent>
    <FloatingPanelHeader>
      <FloatingPanelTitle />
    </FloatingPanelHeader>
    <FloatingPanelBody />
  </FloatingPanelContent>
</FloatingPanel>
```

## Examples [#examples]

### Controlled Size [#controlled-size]

Control the panel size programmatically using the `size` and `onSizeChange` props.

<ComponentPreview componentName="floating-panel" fileName="example-controlled-size" />

### Controlled Position [#controlled-position]

Control the panel position programmatically using the `position` and `onPositionChange` props.

<ComponentPreview componentName="floating-panel" fileName="example-controlled-position" />

### Custom spacing [#custom-spacing]

Use `[--space:--spacing("value")]` on `FloatingPanelContent` to adjust internal padding.

Default spacing is `--spacing(4)`.

<ComponentPreview componentName="floating-panel" fileName="example-custom-spacing" />

> You can use breakpoint utilities to change the internal spacing at different screen sizes.

```css
  md:[--space:--spacing(6)] lg:[--space:--spacing(8)]
```

## API Reference [#api-reference]

### FloatingPanel [#floatingpanel]

Root component. Manages panel position and drag state.

| Prop               | Type                                       | Default |
| ------------------ | ------------------------------------------ | ------- |
| `open`             | `boolean`                                  | `-`     |
| `defaultOpen`      | `boolean`                                  | `false` |
| `onOpenChange`     | `(details: OpenChangeDetails) => void`     | `-`     |
| `position`         | `Point`                                    | `-`     |
| `defaultPosition`  | `Point`                                    | `-`     |
| `onPositionChange` | `(details: PositionChangeDetails) => void` | `-`     |
| `size`             | `Size`                                     | `-`     |
| `defaultSize`      | `Size`                                     | `-`     |
| `onSizeChange`     | `(details: SizeChangeDetails) => void`     | `-`     |
| `lazyMount`        | `boolean`                                  | `true`  |
| `unmountOnExit`    | `boolean`                                  | `true`  |
| `closeOnEscape`    | `boolean`                                  | `true`  |
| `draggable`        | `boolean`                                  | `true`  |
| `resizable`        | `boolean`                                  | `true`  |
| `className`        | `string`                                   | `-`     |

### FloatingPanelTrigger [#floatingpaneltrigger]

Opens the floating panel on click.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### FloatingPanelContent [#floatingpanelcontent]

Holds the panel content.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `resizable` | `boolean` | `true`  |
| `className` | `string`  | `-`     |

| Attribute | Default        |
| --------- | -------------- |
| `--space` | `--spacing(4)` |

### FloatingPanelHeader [#floatingpanelheader]

Header area. Acts as drag handle for repositioning.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### FloatingPanelTitle [#floatingpaneltitle]

Title for the panel.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### FloatingPanelBody [#floatingpanelbody]

Scrollable body content. Uses [ScrollArea](/docs/components/scroll-area) for overflow.

| Prop         | Type      | Default |
| ------------ | --------- | ------- |
| `scrollFade` | `boolean` | `false` |
| `className`  | `string`  | `-`     |

### FloatingPanelCloseTrigger [#floatingpanelclosetrigger]

Closes the panel on click.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/floating-panel#api-reference).


# Frame (/docs/components/frame)



<ComponentPreview componentName="frame" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/frame
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/frame.tsx" src="/frame.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Frame
├── FramePanel
└── FrameHeader
    ├── FrameTitle
    ├── FrameDescription
    └── FrameFooter
```

## Usage [#usage]

```tsx
import {
  Frame,
  FrameHeader,
  FrameTitle,
  FrameDescription,
  FramePanel,
  FrameFooter,
} from "@/components/ui/frame";
```

```tsx
<Frame>
  <FrameHeader>
    <FrameTitle>Title</FrameTitle>
    <FrameDescription>Description</FrameDescription>
  </FrameHeader>
  <FramePanel>Content</FramePanel>
  <FrameFooter>Footer</FrameFooter>
</Frame>
```

## Title & Description [#title--description]

`FrameHeader` supports two usage patterns:

### Using props [#using-props]

Pass `title` and `description` props directly to `FrameHeader`.

```tsx showLineNumbers
<FrameHeader title="Frame Title" description="Frame description" />
```

> This approach does not require `FrameTitle` or `FrameDescription` components.

### Using components [#using-components]

Use `FrameTitle` and `FrameDescription` as children for more control.

```tsx showLineNumbers
<FrameHeader>
  <FrameTitle>Frame Title</FrameTitle>
  <FrameDescription>Frame description</FrameDescription>
</FrameHeader>
```

## Examples [#examples]

### Separated Panels [#separated-panels]

By default, multiple panels are separated with spacing between them.

<ComponentPreview componentName="frame" fileName="example-separated-panels" />

## API Reference [#api-reference]

### Frame [#frame]

Main container for grouping related content into panels.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### FramePanel [#framepanel]

A single panel with optional header and footer.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### FrameHeader [#frameheader]

Header area for the panel. Often contains title and description.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### FrameTitle [#frametitle]

Panel title or heading.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### FrameDescription [#framedescription]

Panel description or subtitle.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### FrameFooter [#framefooter]

Footer area for the panel. Often contains actions.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |


# Hint (/docs/components/hint)



<Alert>
  <InfoIcon />

  <AlertDescription>
    For the full Tooltip component, check out the [Tooltip](/docs/components/tooltip) component.
  </AlertDescription>
</Alert>

<ComponentPreview componentName="hint" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/hint
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/hint.tsx" src="/hint.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Hint
├── HintTrigger
└── HintContent
```

## Usage [#usage]

```tsx
import { Hint, HintTrigger, HintContent } from "@/components/ui/hint";
```

```tsx
<Hint>
  <HintTrigger />
  <HintContent />
</Hint>
```

## Hint vs Tooltip [#hint-vs-tooltip]

* **Hint**: A lightweight, minimal tooltip that shows information, no external dependencies.

* **Tooltip**: A more complex component that provides a more full-featured tooltip with a variety of options.

## Controlled [#controlled]

Pass `open` and `onOpenChange` to controlled hint.

<ComponentPreview componentName="hint" fileName="example-controlled" />

## Examples [#examples]

### Positions [#positions]

<ComponentPreview componentName="hint" fileName="example-positions" />

## API Reference [#api-reference]

### Hint [#hint]

Root wrapper. Provides hint context to trigger and content.

| Prop           | Type                      | Default                                  |
| -------------- | ------------------------- | ---------------------------------------- |
| `open`         | `boolean`                 | -                                        |
| `defaultOpen`  | `boolean`                 | `false`                                  |
| `onOpenChange` | `(open: boolean) => void` | -                                        |
| `positioning`  | `Positioning`             | `"{ placement: 'top', gutter: '10px' }"` |
| `className`    | `string`                  | -                                        |

| Attribute  | Type     | Default |
| ---------- | -------- | ------- |
| `--gutter` | `string` | `10px`  |

### HintTrigger [#hinttrigger]

Shows the hint on hover or focus. Button by default; use `asChild` for custom elements.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### HintContent [#hintcontent]

Hint content shown in a popover on hover or focus.

| Prop            | Type      | Default |
| --------------- | --------- | ------- |
| `lazyMount`     | `boolean` | `true`  |
| `unmountOnExit` | `boolean` | `true`  |
| `className`     | `string`  | -       |
| `asChild`       | `boolean` | -       |

### HintArrow [#hintarrow]

Arrow pointing to the trigger. Rendered inside `HintContent` by default.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |


# Hover Card (/docs/components/hover-card)



<ComponentPreview componentName="hover-card" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/hover-card
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/hover-card.tsx" src="/hover-card.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
HoverCard
├── HoverCardTrigger
└── HoverCardContent
```

## Usage [#usage]

```tsx
import { 
  HoverCard, 
  HoverCardContent,
  HoverCardTrigger,
} from "@/components/ui/hover-card";
```

```tsx
<HoverCard>
  <HoverCardTrigger />
  <HoverCardContent>
    {/* Content */}
  </HoverCardContent>
</HoverCard>
```

## Triggers Delays [#triggers-delays]

The `openDelay` and `closeDelay` props control the delay before the hover card opens and closes respectively.

Default values are `100ms` for `closeDelay` and `10ms` for `openDelay`.

<ComponentPreview componentName="hover-card" fileName="example-triggers-delays" />

## Positioning [#positioning]

Control the position of the hover card relative to the trigger using the `positioning` prop.

<ComponentPreview componentName="hover-card" fileName="example-positioning" />

## Controlled [#controlled]

Control the open state programmatically using the `open` and `onOpenChange` props.

<ComponentPreview componentName="hover-card" fileName="example-controlled" />

## Disabled [#disabled]

Use the `disabled` prop to prevent the hover card from opening on hover.

<ComponentPreview componentName="hover-card" fileName="example-disabled" />

## API Reference [#api-reference]

### HoverCard [#hovercard]

Root component. Manages hover state and content visibility.

| Prop           | Type                                   | Default                |
| -------------- | -------------------------------------- | ---------------------- |
| `closeDelay`   | `number`                               | `100`                  |
| `defaultOpen`  | `boolean`                              | -                      |
| `disabled`     | `boolean`                              | -                      |
| `immediate`    | `boolean`                              | -                      |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | -                      |
| `open`         | `boolean`                              | -                      |
| `openDelay`    | `number`                               | `10`                   |
| `positioning`  | `PositioningOptions`                   | `{ placement: "top" }` |
| `className`    | `string`                               | `-`                    |

### HoverCardTrigger [#hovercardtrigger]

Shows the hover card on hover or focus.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | -       |

### HoverCardContent [#hovercardcontent]

Content shown in a popover when hover card is open.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | -       |

### HoverCardArrow [#hovercardarrow]

Optional arrow pointing toward the trigger.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | -       |

| Attribute            | Default                      |
| -------------------- | ---------------------------- |
| `--arrow-background` | `var(--popover)`             |
| `--arrow-size`       | `calc(1.5 * var(--spacing))` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/hover-card#api-reference).


# Image Cropper (/docs/components/image-cropper)



<ComponentPreview componentName="image-cropper" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/image-cropper
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/image-cropper.tsx" src="/image-cropper.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
ImageCropper
├── ImageCropperImage
├── ImageCropperSelection
├── ImageCropperHandle
└── ImageCropperGrid
```

## Usage [#usage]

```tsx
import {
  ImageCropper,
  ImageCropperImage,
  ImageCropperSelection,
} from "@/components/ui/image-cropper";
```

```tsx
<ImageCropper>
  <ImageCropperImage alt="Crop me" src="/image.jpg" />
  <ImageCropperSelection />
</ImageCropper>
```

## Examples [#examples]

### Aspect ratio [#aspect-ratio]

Use the `aspectRatio` to lock the crop area to a specific aspect ratio.

<ComponentPreview componentName="image-cropper" fileName="example-aspect-ratio" />

### Circle crop [#circle-crop]

Use `cropShape="circle"` for profile pictures or avatars.

<ComponentPreview componentName="image-cropper" fileName="example-circle-crop" />

### Initial crop [#initial-crop]

Start with a pre-defined crop area using the `initialCrop` prop.

<ComponentPreview componentName="image-cropper" fileName="example-initial-crop" />

### Controlled zoom [#controlled-zoom]

Control zoom programmatically with the `zoom` and `onZoomChange` props.

<ComponentPreview componentName="image-cropper" fileName="example-controlled-zoom" />

### Zoom limits [#zoom-limits]

Set `minZoom` and `maxZoom` to constrain how far users can zoom.

<ComponentPreview componentName="image-cropper" fileName="example-zoom-limits" />

### Min and max size [#min-and-max-size]

Constrain the crop area size with `minWidth`, `minHeight`, `maxWidth`, and `maxHeight`.

<ComponentPreview componentName="image-cropper" fileName="example-min-max-size" />

### Fixed crop area [#fixed-crop-area]

Set `fixedCropArea` to `true` when the crop area should stay fixed while the image moves underneath.

<ComponentPreview componentName="image-cropper" fileName="example-fixed-crop-area" />

## API Reference [#api-reference]

### ImageCropper [#imagecropper]

Root wrapper. Manages crop state and handles.

| Prop            | Type                                                      | Default       |
| --------------- | --------------------------------------------------------- | ------------- |
| `aspectRatio`   | `number`                                                  | -             |
| `cropShape`     | `"circle" \| "rectangle"`                                 | `"rectangle"` |
| `fixedCropArea` | `boolean`                                                 | `false`       |
| `initialCrop`   | `{ x: number; y: number; width: number; height: number }` | -             |
| `maxHeight`     | `number`                                                  | `Infinity`    |
| `maxWidth`      | `number`                                                  | `Infinity`    |
| `maxZoom`       | `number`                                                  | `5`           |
| `minHeight`     | `number`                                                  | `40`          |
| `minWidth`      | `number`                                                  | `40`          |
| `minZoom`       | `number`                                                  | `1`           |
| `onCropChange`  | `(details: CropChangeDetails) => void`                    | -             |
| `onZoomChange`  | `(details: ZoomChangeDetails) => void`                    | -             |
| `rotation`      | `number`                                                  | -             |
| `zoom`          | `number`                                                  | -             |
| `className`     | `string`                                                  | -             |

| Attribute                 | Default              |
| ------------------------- | -------------------- |
| `--cropper-accent`        | `var(--color-white)` |
| `--cropper-handler-size`  | `--spacing(2)`       |
| `--cropper-handler-width` | `--spacing(1)`       |

### ImageCropperImage [#imagecropperimage]

Image to crop. Pass `src` and alt.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `alt`       | `string` | -       |
| `src`       | `string` | -       |
| `className` | `string` | -       |

### ImageCropperSelection [#imagecropperselection]

Crop selection overlay with resize handles and optional grid.

| Prop        | Type                                   | Default  |
| ----------- | -------------------------------------- | -------- |
| `axis`      | `"horizontal" \| "vertical" \| "both"` | `"both"` |
| `className` | `string`                               | -        |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/image-cropper#api-reference).


# Input Group (/docs/components/input-group)



<ComponentPreview componentName="input-group" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/input-group
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Input](/docs/components/input)

        , 

        [Button](/docs/components/button)

        , and 

        [Textarea](/docs/components/textarea)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/input-group.tsx" src="/input-group.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
InputGroup
├── InputGroupAddon
├── InputGroupButton
├── InputGroupText
├── InputGroupInput
└── InputGroupTextarea
```

## Usage [#usage]

```tsx
import { 
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@/components/ui/input-group";
```

```tsx
<InputGroup>
  <InputGroupInput />
  <InputGroupAddon>
    <InputGroupText>https://</InputGroupText>
  </InputGroupAddon>
</InputGroup>
```

## Align [#align]

Use the `align` prop to change the alignment of the input group.

### inline-start [#inline-start]

<ComponentPreview componentName="input-group" fileName="example-align-inline-start" />

### inline-end [#inline-end]

<ComponentPreview componentName="input-group" fileName="example-align-inline-end" />

### block-start [#block-start]

<ComponentPreview componentName="input-group" fileName="example-align-block-start" />

### block-end [#block-end]

<ComponentPreview componentName="input-group" fileName="example-align-block-end" />

## Size [#size]

Use the `size` prop to change the size of the input group.

### Small [#small]

<ComponentPreview componentName="input-group" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="input-group" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="input-group" fileName="example-size-lg" />

## States [#states]

### Disabled [#disabled]

<ComponentPreview componentName="input-group" fileName="example-disabled" />

### Invalid [#invalid]

<ComponentPreview componentName="input-group" fileName="example-invalid" />

## Examples [#examples]

### With Tooltip [#with-tooltip]

<ComponentPreview componentName="input-group" fileName="example-with-tooltip" />

### With Button [#with-button]

<ComponentPreview componentName="input-group" fileName="example-with-button" />

### With Menu [#with-menu]

<ComponentPreview componentName="input-group" fileName="example-with-menu" />

### With Badge [#with-badge]

<ComponentPreview componentName="input-group" fileName="example-with-badge" />

### With Keyboard Shortcut [#with-keyboard-shortcut]

<ComponentPreview componentName="input-group" fileName="example-with-keyboard-shortcut" />

### With Inner Label [#with-inner-label]

<ComponentPreview componentName="input-group" fileName="example-with-inner-label" />

### With Spinner [#with-spinner]

<ComponentPreview componentName="input-group" fileName="example-with-spinner" />

### With Number Field [#with-number-field]

<ComponentPreview componentName="input-group" fileName="example-with-number-input" />

### With Input Group [#with-input-group]

Use `FieldGroup` with textarea to build forms. Combine subject input, message textarea, and action buttons.

<ComponentPreview componentName="input-group" fileName="example-input-group" />

### Password Strength Checker [#password-strength-checker]

A complete password checker with show/hide toggle, clear button, and real-time strength indicator. A strong password requires at least 8 characters with uppercase, lowercase, number, and special character.

<ComponentPreview componentName="input-group" fileName="example-password-strength-checker" />

## API Reference [#api-reference]

### InputGroup [#inputgroup]

Wraps input with optional addons (labels, buttons, icons) on any side.

| Prop        | Type                   | Default |
| ----------- | ---------------------- | ------- |
| `size`      | `"sm" \| "md" \| "lg"` | `"md"`  |
| `className` | `string`               | -       |

### InputGroupAddon [#inputgroupaddon]

Holds addon content (labels, buttons, icons) beside the input.

| Prop        | Type                                                             | Default          |
| ----------- | ---------------------------------------------------------------- | ---------------- |
| `align`     | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` |
| `className` | `string`                                                         | -                |

### InputGroupButton [#inputgroupbutton]

Button inside an addon. Typically used for reveal/hide, clear, or search.

| Prop        | Type                                              | Default    |
| ----------- | ------------------------------------------------- | ---------- |
| `size`      | [ButtonSize](/docs/components/button#sizes)       | `"xs"`     |
| `variant`   | [ButtonVariant](/docs/components/button#variants) | `"ghost"`  |
| `type`      | `"button" \| "submit" \| "reset"`                 | `"button"` |
| `className` | `string`                                          | -          |

### InputGroupText [#inputgrouptext]

Static text label inside an addon.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### InputGroupInput [#inputgroupinput]

Text input. Accepts all native input props.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### InputGroupTextarea [#inputgrouptextarea]

Multi-line text input. Accepts all native textarea props.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |


# Input OTP (/docs/components/input-otp)



<ComponentPreview componentName="input-otp" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/input-otp
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Input](/docs/components/input)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/input-otp.tsx" src="/input-otp.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
InputOTP
├── InputOTPSlot
└── InputOTPSeparator
```

## Usage [#usage]

```tsx
import {
  InputOTP,
  InputOTPSeparator,
  InputOTPSlot,
} from "@/components/ui/input-otp";
```

```tsx
<InputOTP>
  <InputOTPSlot index={0} />
  <InputOTPSlot index={1} />
  <InputOTPSlot index={2} />
  <InputOTPSeparator />
  <InputOTPSlot index={3} />
  <InputOTPSlot index={4} />
  <InputOTPSlot index={5} />
</InputOTP>
```

## Controlled [#controlled]

Use `value` and `onValueChange` to control the input.

<ComponentPreview componentName="input-otp" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

Use the `disabled` prop to disable the input.

<ComponentPreview componentName="input-otp" fileName="example-disabled" />

### Invalid [#invalid]

Use the `invalid` prop to mark the input as invalid and show error styling.

<ComponentPreview componentName="input-otp" fileName="example-invalid" />

## Examples [#examples]

### Four Digits [#four-digits]

Use four `InputOTPSlot` elements for a 4-digit OTP.

<ComponentPreview componentName="input-otp" fileName="example-four-digits" />

### Separator [#separator]

Add `InputOTPSeparator` between groups of slots.

<ComponentPreview componentName="input-otp" fileName="example-separator" />

### With Placeholder [#with-placeholder]

Use the `placeholder` prop to show a placeholder in each slot.

<ComponentPreview componentName="input-otp" fileName="example-with-placeholder" />

### Blur on Complete [#blur-on-complete]

Use the `blurOnComplete` prop to blur the input when all slots are filled.

<ComponentPreview componentName="input-otp" fileName="example-blur-on-complete" />

### Mask [#mask]

Use the `mask` prop to mask the input value.

<ComponentPreview componentName="input-otp" fileName="example-mask" />

### Custom Size [#custom-size]

Pass `*:data-[slot=input-otp-input]:size-*` and `*:data-[slot=input-otp-input]:text-*` to `InputOTP` to override slot dimensions and text size.

<ComponentPreview componentName="input-otp" fileName="example-custom-size" />

## API Reference [#api-reference]

### InputOTP [#inputotp]

| Prop             | Type                                 | Default |
| ---------------- | ------------------------------------ | ------- |
| `withFakeCaret`  | `boolean`                            | `false` |
| `value`          | `string`                             | -       |
| `defaultValue`   | `string`                             | -       |
| `onValueChange`  | `({ value, valueAsString }) => void` | -       |
| `disabled`       | `boolean`                            | -       |
| `invalid`        | `boolean`                            | -       |
| `otp`            | `boolean`                            | `true`  |
| `blurOnComplete` | `boolean`                            | -       |
| `mask`           | `boolean`                            | -       |

### InputOTPSlot [#inputotpslot]

Single OTP slot. Use `index` to specify position, 0 is the first slot.

| Prop    | Type     | Default      |
| ------- | -------- | ------------ |
| `index` | `number` | **required** |

### InputOTPSeparator [#inputotpseparator]

Visual separator between slots.

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/pin-input#api-reference).


# Input (/docs/components/input)



<ComponentPreview componentName="input" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/input
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/input.tsx" src="/input.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Input } from "@/components/ui/input";
```

```tsx
<Input />
```

## Controlled [#controlled]

Control the value with `value` and `onChange`.

<ComponentPreview componentName="input" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

Use the `disabled` prop to disable the input.

<ComponentPreview componentName="input" fileName="example-disabled" />

### Invalid [#invalid]

Use the `invalid` prop to mark the input as invalid.

<ComponentPreview componentName="input" fileName="example-invalid" />

## Sizes [#sizes]

Use the `size` prop to change the input height.

### Small [#small]

<ComponentPreview componentName="input" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="input" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="input" fileName="example-size-lg" />

## Examples [#examples]

### With Field [#with-field]

Use [Field](/docs/components/field) components to create an input with a label and a description.

<ComponentPreview componentName="input" fileName="example-field" />

### Field Group [#field-group]

Use `FieldGroup` to show multiple `Field` blocks and to build forms.

<ComponentPreview componentName="input" fileName="example-field-group" />

### File [#file]

Use the `type="file"` prop to create a file input.

<ComponentPreview componentName="input" fileName="example-file" />

<Alert>
  <InfoIcon />

  <AlertTitle>
    Dedicated File Upload component
  </AlertTitle>

  <AlertDescription>
    For more advanced file upload functionality, use the [FileUpload](/docs/components/file-upload) component instead.
  </AlertDescription>
</Alert>

### Inline [#inline]

Use the `orientation="horizontal"` prop to create an inline input.

<ComponentPreview componentName="input" fileName="example-inline" />

### Grid [#grid]

<ComponentPreview componentName="input" fileName="example-grid" />

### Badge [#badge]

Use `Badge` in the label to highlight a recommended field.

<ComponentPreview componentName="input" fileName="example-badge" />

### Input Group [#input-group]

Use `InputGroup` to create an input group.

<ComponentPreview componentName="input" fileName="example-input-group" />

### Button Group [#button-group]

Use `ButtonGroup` to create a button group.

<ComponentPreview componentName="input" fileName="example-button-group" />

## API Reference [#api-reference]

### Input [#input]

Text input. Accepts all native input attributes.

| Prop        | Type                   | Default |
| ----------- | ---------------------- | ------- |
| `size`      | `"sm" \| "md" \| "lg"` | `"md"`  |
| `type`      | `string`               | `text`  |
| `className` | `string`               | `-`     |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/field#api-reference).


# Item (/docs/components/item)



<ComponentPreview componentName="item" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/item
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Separator](/docs/components/separator)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/item.tsx" src="/item.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
ItemGroup
├── ItemSeparator
└── Item
    ├── ItemMedia
    ├── ItemHeader
    ├── ItemContent
    │   ├── ItemTitle
    │   └── ItemDescription
    ├── ItemActions
    └── ItemFooter
```

## Usage [#usage]

```tsx
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@/components/ui/item";
```

```tsx
<Item>
  <ItemMedia />
  <ItemContent>
    <ItemTitle />
    <ItemDescription />
  </ItemContent>
  <ItemActions />
</Item>
```

## Variant [#variant]

### Default [#default]

<ComponentPreview componentName="item" fileName="example-variant-default" />

### Outline [#outline]

<ComponentPreview componentName="item" fileName="example-variant-outline" />

### Muted [#muted]

<ComponentPreview componentName="item" fileName="example-variant-muted" />

## Custom spacing [#custom-spacing]

The `[--space:--spacing("value")]` on `ItemContent` controls the internal spacing.

Default spacing is `--spacing(3)`.

<ComponentPreview componentName="item" fileName="example-custom-spacing" />

> You can use breakpoint utilities to change the internal spacing at different screen sizes.

```css
  md:[--space:--spacing(6)] lg:[--space:--spacing(8)]
```

## Examples [#examples]

### Icon [#icon]

<ComponentPreview componentName="item" fileName="example-icon" />

### Avatar [#avatar]

<ComponentPreview componentName="item" fileName="example-avatar" />

### Image [#image]

<ComponentPreview componentName="item" fileName="example-image" />

### Group [#group]

Use `ItemGroup` to group related items together.

<ComponentPreview componentName="item" fileName="example-group" />

### Header [#header]

Use `ItemHeader` to add a header above the item content.

<ComponentPreview componentName="item" fileName="example-header" />

### Link [#link]

Use the `asChild` prop to render the item as a link. The hover and focus states will be applied to the anchor element.

<ComponentPreview componentName="item" fileName="example-link" />

### Dropdown [#dropdown]

Use `Item` inside a menu or dropdown to display rich content in menu items.

<ComponentPreview componentName="item" fileName="example-dropdown" />

## API Reference [#api-reference]

### Item [#item]

Layout for list items with media, title, description, and actions. Use `[--space:--spacing("value")]` via `className` to control padding and gap. Supports `asChild`.

| Prop        | Type                                | Default     |
| ----------- | ----------------------------------- | ----------- |
| `variant`   | `"default" \| "outline" \| "muted"` | `"default"` |
| `asChild`   | `boolean`                           | `false`     |
| `className` | `string`                            | -           |

| Attribute | Default        |
| --------- | -------------- |
| `--space` | `--spacing(3)` |

### ItemGroup [#itemgroup]

Groups related items with consistent spacing. Uses a fixed gap; adjust layout with `className` if needed. Has `role="list"` for accessibility.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### ItemSeparator [#itemseparator]

Horizontal divider between items in a group.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### ItemMedia [#itemmedia]

Avatar, icon, or image for the item. Supports icon and image variants.

| Prop        | Type                             | Default     |
| ----------- | -------------------------------- | ----------- |
| `variant`   | `"default" \| "icon" \| "image"` | `"default"` |
| `className` | `string`                         | -           |
| `asChild`   | `boolean`                        | `false`     |

### ItemContent [#itemcontent]

Wraps the item title and description text.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### ItemTitle [#itemtitle]

Primary title or heading for the item.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### ItemDescription [#itemdescription]

Secondary description or subtitle for the item.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### ItemActions [#itemactions]

Holds action buttons or controls.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### ItemHeader [#itemheader]

Full-width header row above the item content.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### ItemFooter [#itemfooter]

Full-width footer row below the item content.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |


# Kbd (/docs/components/kbd)



<ComponentPreview componentName="kbd" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/kbd
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/kbd.tsx" src="/kbd.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Kbd

KbdGroup
├── Kbd
└── Kbd
```

## Usage [#usage]

```tsx
import { 
  Kbd, 
  KbdGroup 
} from "@/components/ui";
```

```tsx
<KbdGroup>
  <Kbd>⌘</Kbd>
  <Kbd>K</Kbd>
</KbdGroup>
```

## Variant [#variant]

### Outline [#outline]

<ComponentPreview componentName="kbd" fileName="example-variant-outline" />

## Examples [#examples]

### Group [#group]

Use `KbdGroup` to group keys into a single shortcut.

<ComponentPreview componentName="kbd" fileName="example-kbd-group" />

### Input Group [#input-group]

Use `Kbd` inside `InputGroup` addons to show shortcut hints next to inputs.

<ComponentPreview componentName="kbd" fileName="example-input-group" />

### Button [#button]

Add shortcut hints to buttons with `Kbd` or `KbdGroup`.

<ComponentPreview componentName="kbd" fileName="example-button" />

### Tooltip [#tooltip]

Show keyboard shortcuts in `Tooltip` content.

<ComponentPreview componentName="kbd" fileName="example-tooltip" />

## API Reference [#api-reference]

### Kbd [#kbd]

Styled representation of a single key.

| Prop        | Type                     | Default     |
| ----------- | ------------------------ | ----------- |
| `variant`   | `"default" \| "outline"` | `"default"` |
| `className` | `string`                 | -           |
| `asChild`   | `boolean`                | `false`     |

### KbdGroup [#kbdgroup]

Groups multiple keys into one shortcut.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |


# Link Overlay (/docs/components/link-overlay)



<ComponentPreview componentName="link-overlay" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/link-overlay
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/link-overlay.tsx" src="/link-overlay.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
LinkBox
└── LinkOverlay
```

## Usage [#usage]

```tsx
import { 
  LinkBox, 
  LinkOverlay
} from "@/components/ui/link-overlay";
```

```tsx
<LinkBox>
  <h2>
    <LinkOverlay href="/blog/post-1">
      Blog Post Title
    </LinkOverlay>
  </h2>
</LinkBox>
```

## Accessibility [#accessibility]

* **Wrapping a whole card in `<a>`** — Screen readers announce all card content as link text (verbose, confusing).
* **`LinkOverlay`** — Keeps the link on the heading only. Announcements stay short.
* **Full area clickable** — The overlay makes the whole card clickable without extra markup.
* **Inner links** — Stay above the overlay and remain focusable. Users can tab between multiple links instead of one.

## Link [#link]

The `asChild` prop renders another element with link overlay styling.

<ComponentPreview componentName="link-overlay" fileName="example-with-link" />

## Examples [#examples]

### Article [#article]

A blog-style article with metadata, heading, description, and an inner link that stays clickable above the overlay.

<ComponentPreview componentName="link-overlay" fileName="example-article" />

### Always use Link [#always-use-link]

By default the `LinkOverlay` component will render an `a` tag.

To use the Next.js (or any other) `Link` component, make the following updates to `link-overlay.tsx`.

```diff tsx title="components/ui/link-overlay.tsx" showLineNumbers
+ import Link from "next/link"
- import { ark } from "@ark-ui/react/factory"

- export const LinkOverlay = (props: React.ComponentProps<typeof ark.a>) => {
+ export const LinkOverlay = (props: React.ComponentProps<typeof Link>) => {
  const { className, ...rest } = props;

  return (
-    <ark.a
+    <Link
      ...
```

## API Reference [#api-reference]

### LinkBox [#linkbox]

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### LinkOverlay [#linkoverlay]

| Prop        | Type      | Default  |
| ----------- | --------- | -------- |
| `href`      | `string`  | required |
| `className` | `string`  | -        |
| `asChild`   | `boolean` | `false`  |


# Listbox (/docs/components/listbox)



<ComponentPreview componentName="listbox" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/listbox
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Menu](/docs/components/menu)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/listbox.tsx" src="/listbox.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Listbox
├── ListboxValueText
└── ListboxContent
    ├── ListboxEmpty
    └── ListboxItemGroup
        ├── ListboxItemGroupLabel
        └── ListboxItem
            ├── ListboxItemText
            ├── ListboxItemIndicator
            └── ListboxShortcut
```

## Usage [#usage]

```tsx
import { createListCollection } from "@ark-ui/react";
import {
  Listbox,
  ListboxContent,
  ListboxItem,
  ListboxLabel,
} from "@/components/ui/listbox";
```

```tsx
const collection = createListCollection({
  items: [
    { label: "Brazil", value: "br" },
    { label: "Mexico", value: "mx" },
    { label: "Ireland", value: "ie" },
  ],
});

<Listbox collection={collection}>
  <ListboxContent>
    {collection.items.map((item) => (
      <ListboxItem item={item} key={item.value}>
        {item.label}
      </ListboxItem>
    ))}
  </ListboxContent>
</Listbox>
```

## Controlled [#controlled]

Use `value` and `onValueChange` to control the listbox externally.

<ComponentPreview componentName="listbox" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

Disable the entire listbox with the `disabled` prop.

<ComponentPreview componentName="listbox" fileName="example-disabled" />

## Orientation [#orientation]

Use `orientation` prop to change the orientation of the listbox.

### Horizontal [#horizontal]

<ComponentPreview componentName="listbox" fileName="example-horizontal" />

## Selection Mode [#selection-mode]

### Multiple [#multiple]

Set `selectionMode="multiple"` to allow selecting multiple items.

<ComponentPreview componentName="listbox" fileName="example-selection-multiple" />

### Extended [#extended]

Set `selectionMode="extended"` to select multiple items with Cmd/Ctrl modifier.

<ComponentPreview componentName="listbox" fileName="example-selection-extended" />

### None [#none]

Set `selectionMode="none"` to disable selection.

<ComponentPreview componentName="listbox" fileName="example-selection-none" />

## Examples [#examples]

### With Icon [#with-icon]

<ComponentPreview componentName="listbox" fileName="example-with-icon" />

### With Description [#with-description]

<ComponentPreview componentName="listbox" fileName="example-with-description" />

### Image Explorer [#image-explorer]

<ComponentPreview componentName="listbox" fileName="example-image-explorer" />

### Transfer List [#transfer-list]

<ComponentPreview componentName="listbox" fileName="example-transfer-list" />

### Grouping [#grouping]

Use `groupBy` in `createListCollection` and `<ListboxItemGroup heading={}>` with `<ListboxItemGroupLabel>` to group items.

<ComponentPreview componentName="listbox" fileName="example-grouping" />

### With Filter [#with-filter]

Filter items using `useListCollection` with `useFilter` from `@ark-ui/react`. Call `filter` when the search input changes to filter items by label.

<ComponentPreview componentName="listbox" fileName="example-with-filter" />

### With Popover [#with-popover]

Use the listbox within a popover to create dropdown-like selection menus that overlay other content without taking up permanent screen space.

<ComponentPreview componentName="listbox" fileName="example-with-popover" />

### Grid Layout [#grid-layout]

Use `createGridCollection` with `columnCount` and grid CSS for a grid layout.

<ComponentPreview componentName="listbox" fileName="example-grid" />

## API Reference [#api-reference]

### Listbox [#listbox]

Root component. Manages selection state and keyboard navigation.

| Prop            | Type                                       | Default      |
| --------------- | ------------------------------------------ | ------------ |
| `collection`    | `ListCollection<T>`                        | **required** |
| `value`         | `string[]`                                 | -            |
| `defaultValue`  | `string[]`                                 | `[]`         |
| `onValueChange` | `(details: ValueChangeDetails<T>) => void` | -            |
| `selectionMode` | `"single" \| "multiple" \| "extended"`     | `"single"`   |
| `orientation`   | `"vertical" \| "horizontal"`               | `"vertical"` |
| `disabled`      | `boolean`                                  | -            |
| `deselectable`  | `boolean`                                  | -            |
| `loopFocus`     | `boolean`                                  | `false`      |

### ListboxContent [#listboxcontent]

Holds the list of options.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | -       |

### ListboxItem [#listboxitem]

A single selectable list option.

| Prop               | Type                         | Default      |
| ------------------ | ---------------------------- | ------------ |
| `item`             | `T`                          | **required** |
| `variant`          | `"default" \| "destructive"` | `"default"`  |
| `asChild`          | `boolean`                    | -            |
| `highlightOnHover` | `boolean`                    | -            |

### ListboxItemText [#listboxitemtext]

Text content for a list item.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | -       |

### ListboxItemIndicator [#listboxitemindicator]

Checkmark or icon shown when the item is selected.

| Prop        | Type        | Default     |
| ----------- | ----------- | ----------- |
| `children`  | `ReactNode` | `CheckIcon` |
| `asChild`   | `boolean`   | -           |
| `className` | `string`    | -           |

### ListboxItemGroup [#listboxitemgroup]

Groups related options. Use `heading` or `ListboxItemGroupLabel` for a label.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `heading`   | `string`  | -       |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | -       |

### ListboxItemGroupLabel [#listboxitemgrouplabel]

Label for a group. Must be used inside `ListboxItemGroup`.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | -       |

### ListboxValueText [#listboxvaluetext]

Shows the selected value(s) as text. Use for custom trigger or display.

| Prop          | Type      | Default |
| ------------- | --------- | ------- |
| `placeholder` | `string`  | -       |
| `asChild`     | `boolean` | -       |
| `className`   | `string`  | -       |

### ListboxEmpty [#listboxempty]

Shown when the list has no items. Use for empty states.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | -       |

### ListboxShortcut [#listboxshortcut]

Optional keyboard shortcut hint shown next to an item.

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/listbox#api-reference).


# Marquee (/docs/components/marquee)



<ComponentPreview componentName="marquee" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/marquee
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Add the following animations to your 

        `globals.css`

        .
      </Step>

      ```css title="globals.css" showLineNumbers
      @theme inline {
        --animate-marquee-x: marqueeX var(--marquee-duration) linear infinite var(--marquee-delay);
        --animate-marquee-y: marqueeY var(--marquee-duration) linear infinite var(--marquee-delay);

        @keyframes marqueeX {
          from { transform: translateX(0); }
          to { transform: translateX(var(--marquee-translate)); }
        }
        @keyframes marqueeY {
          from { transform: translateY(0); }
          to { transform: translateY(var(--marquee-translate)); }
        }
      }
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/marquee.tsx" src="/marquee.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Marquee
├── MarqueeContent
    └── MarqueeItem
```

## Usage [#usage]

```tsx
import { 
  Marquee, 
  MarqueeContent, 
  MarqueeItem,
} from "@/components/ui/marquee";
```

```tsx
<Marquee>
  <MarqueeContent>
    <MarqueeItem />
    <MarqueeItem />
    <MarqueeItem />
  </MarqueeContent>
</Marquee>
```

## Orientation [#orientation]

Use the `orientation` prop to control the orientation of the marquee.

### Horizontal [#horizontal]

<ComponentPreview componentName="marquee" fileName="example-orientation-horizontal" />

### Vertical [#vertical]

<ComponentPreview componentName="marquee" fileName="example-orientation-vertical" />

## Examples [#examples]

### Pause on hover [#pause-on-hover]

Use the `pauseOnInteraction` prop to pause the marquee on hover or focus.

<ComponentPreview componentName="marquee" fileName="example-pause-on-hover" />

### Reverse [#reverse]

Use the `reverse` prop to scroll in the opposite direction.

<ComponentPreview componentName="marquee" fileName="example-reverse" />

### Auto fill [#auto-fill]

Use the `autoFill` prop to automatically duplicate content to fill the container.

<ComponentPreview componentName="marquee" fileName="example-autofill" />

### Spacing [#spacing]

Use the `spacing` prop to control the gap between items.

<ComponentPreview componentName="marquee" fileName="example-spacing" />

### Fade [#fade]

Use the `showEdges` prop to show or hide the gradient fade at the start and end of the marquee.

<ComponentPreview componentName="marquee" fileName="example-fade" />

### Custom speed [#custom-speed]

Use the `speed` prop (pixels per second) to control scroll speed.

<ComponentPreview componentName="marquee" fileName="example-custom-speed" />

## API Reference [#api-reference]

### Marquee [#marquee]

Root component. Manages the scrolling viewport and animation.

| Prop                 | Type                         | Default        |
| -------------------- | ---------------------------- | -------------- |
| `orientation`        | `"horizontal" \| "vertical"` | `"horizontal"` |
| `speed`              | `number`                     | `50`           |
| `spacing`            | `string`                     | `"16px"`       |
| `showEdges`          | `boolean`                    | `true`         |
| `autoFill`           | `boolean`                    | `false`        |
| `pauseOnInteraction` | `boolean`                    | `false`        |
| `reverse`            | `boolean`                    | `false`        |
| `className`          | `string`                     | -              |

### MarqueeContent [#marqueecontent]

Viewport wrapper. Wrap `MarqueeItem` children with this. Animates content horizontally.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### MarqueeItem [#marqueeitem]

Single item in the scrolling marquee.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/marquee#api-reference).


# Menu (/docs/components/menu)



<ComponentPreview componentName="menu" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/menu
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/menu.tsx" src="/menu.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Menu
├── MenuTrigger
└── MenuPositioner
    └── MenuContent
        ├── MenuGroup
        │   └── MenuGroupLabel
        ├── MenuItem
        ├── MenuQuickItem
        ├── MenuCheckboxItem
        ├── MenuRadioGroup
        │   └── MenuRadioItem
        ├── MenuSub
        │   ├── MenuSubTrigger
        │   └── MenuSubContent
        ├── MenuSeparator
        ├── MenuShortcut
        └── MenuArrow
```

## Usage [#usage]

```tsx
import {
  Menu,
  MenuCheckboxItem,
  MenuContent,
  MenuGroup,
  MenuItem,
  MenuQuickItem,
  MenuRadioGroup,
  MenuRadioItem,
  MenuSeparator,
  MenuShortcut,
  MenuSub,
  MenuSubContent,
  MenuSubTrigger,
  MenuTrigger,
} from "@/components/ui/menu";
```

```tsx
<Menu>
  <MenuTrigger />
  <MenuContent>
    <MenuItemGroup>
      <MenuItemGroupLabel />
      <MenuItem />
      <MenuSub>
        <MenuSubTrigger />
        <MenuSubContent>
          <MenuItem />
        </MenuSubContent>
      </MenuSub>
      <MenuSeparator />
      <MenuItemGroup>
        <MenuRadioItem />
      </MenuItemGroup>
      <MenuSeparator />
      <MenuCheckboxItem />
    </MenuItemGroup>
  </MenuContent>
</Menu>
```

## Positioning [#positioning]

Control the position of the menu relative to the trigger using the `positioning` prop.

<ComponentPreview componentName="menu" fileName="example-positioning" />

## Examples [#examples]

### Nested Menu [#nested-menu]

Use `MenuSub`, `MenuSubTrigger`, and `MenuSubContent` for nested submenus.

<ComponentPreview componentName="menu" fileName="example-nested" />

### Icons [#icons]

Combine icons with labels for quick scanning.

<ComponentPreview componentName="menu" fileName="example-icons" />

### Shortcuts [#shortcuts]

Use `MenuShortcut` to show keyboard hints next to menu items.

<ComponentPreview componentName="menu" fileName="example-shortcuts" />

### Checkboxes [#checkboxes]

Use `MenuCheckboxItem` for toggles.

<ComponentPreview componentName="menu" fileName="example-checkboxes" />

### Radio Group [#radio-group]

Use `MenuRadioGroup` and `MenuRadioItem` for a single selection from a set of options.

<ComponentPreview componentName="menu" fileName="example-radio-group" />

### With Link [#with-link]

Use the `asChild` prop on `MenuItem` with a `anchor` element to render a link.

<ComponentPreview componentName="menu" fileName="example-link" />

### With Group Label [#with-group-label]

Use `MenuGroup` with  `MenuGroupLabel` or the `heading` prop to group related items under a label.

<ComponentPreview componentName="menu" fileName="example-group-label" />

### With Separator [#with-separator]

Use `MenuSeparator` to add visual dividers between related groups of menu items.

<ComponentPreview componentName="menu" fileName="example-with-separator" />

### Quick Items [#quick-items]

Use `MenuQuickItem` for actions with icon-above-text layout, ideal for quick actions like Copy and Share displayed horizontally.

<ComponentPreview componentName="menu" fileName="example-quick-item" />

### With Scroll [#with-scroll]

Add `max-h-*` and `overflow-y-auto` to `MenuContent` to constrain height and enable native scrolling when there are many items.

<ComponentPreview componentName="menu" fileName="example-with-scroll" />

### Open a Dialog [#open-a-dialog]

Open a dialog from a `MenuItem` with the `onSelect` prop and controlled state.

<ComponentPreview componentName="menu" fileName="example-dialog" />

### Destructive [#destructive]

Use `variant="destructive"` on `MenuItem` for irreversible actions like delete.

<ComponentPreview componentName="menu" fileName="example-destructive" />

## API Reference [#api-reference]

### Menu [#menu]

Root element of the menu component.

| Prop            | Type                                   | Default |
| --------------- | -------------------------------------- | ------- |
| `positioning`   | `PositioningOptions`                   | -       |
| `open`          | `boolean`                              | -       |
| `defaultOpen`   | `boolean`                              | -       |
| `onOpenChange`  | `(details: OpenChangeDetails) => void` | -       |
| `onSelect`      | `(details: SelectionDetails) => void`  | -       |
| `closeOnSelect` | `boolean`                              | `true`  |

### MenuTrigger [#menutrigger]

Opens the menu on click. Use `asChild` to delegate to a child element.

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | -       |

### MenuContent [#menucontent]

Holds menu options. Displayed in a portal, positioned relative to the trigger.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | -       |

### MenuItem [#menuitem]

A single selectable menu option. Supports `asChild` for custom elements.

| Prop            | Type                         | Default      |
| --------------- | ---------------------------- | ------------ |
| `value`         | `string`                     | **required** |
| `variant`       | `"default" \| "destructive"` | `"default"`  |
| `asChild`       | `boolean`                    | -            |
| `disabled`      | `boolean`                    | -            |
| `closeOnSelect` | `boolean`                    | -            |
| `onSelect`      | `VoidFunction`               | -            |

### MenuCheckboxItem [#menucheckboxitem]

A menu option with a checkbox. Use `checked` and `onCheckedChange` for controlled state.

| Prop              | Type                         | Default      |
| ----------------- | ---------------------------- | ------------ |
| `value`           | `string`                     | **required** |
| `checked`         | `boolean`                    | -            |
| `onCheckedChange` | `(checked: boolean) => void` | -            |
| `disabled`        | `boolean`                    | -            |

### MenuRadioGroup [#menuradiogroup]

Group of mutually exclusive options. Use `value` and `onValueChange` for controlled state.

| Prop            | Type                                    | Default |
| --------------- | --------------------------------------- | ------- |
| `value`         | `string`                                | -       |
| `onValueChange` | `(details: ValueChangeDetails) => void` | -       |
| `heading`       | `string`                                | -       |

### MenuRadioItem [#menuradioitem]

A single option in a radio group.

| Prop       | Type      | Default      |
| ---------- | --------- | ------------ |
| `value`    | `string`  | **required** |
| `disabled` | `boolean` | -            |

### MenuGroup [#menugroup]

Groups related items. Use `heading` or `MenuGroupLabel` for a label.

| Prop      | Type     | Default |
| --------- | -------- | ------- |
| `heading` | `string` | -       |

### MenuGroupLabel [#menugrouplabel]

Label for a group. Must be used inside `MenuGroup`.

### MenuSeparator [#menuseparator]

Visual divider between groups of menu items.

### MenuQuickItem [#menuquickitem]

A menu option with icon-above-text layout for quick actions. Use with `flex` to display multiple items horizontally.

| Prop            | Type           | Default      |
| --------------- | -------------- | ------------ |
| `value`         | `string`       | **required** |
| `asChild`       | `boolean`      | -            |
| `disabled`      | `boolean`      | -            |
| `closeOnSelect` | `boolean`      | -            |
| `onSelect`      | `VoidFunction` | -            |

### MenuSub / MenuSubTrigger / MenuSubContent [#menusub--menusubtrigger--menusubcontent]

Submenu: wrap a nested `Menu`-like structure. `MenuSubTrigger` opens the submenu; `MenuSubContent` holds the nested items.

### MenuShortcut [#menushortcut]

Optional keyboard shortcut hint displayed next to a menu item.

### MenuArrow [#menuarrow]

Optional arrow pointing toward the trigger.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

| Attribute            | Default                      |
| -------------------- | ---------------------------- |
| `--arrow-background` | `var(--popover)`             |
| `--arrow-size`       | `calc(1.5 * var(--spacing))` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/menu#api-reference).


# Native Select (/docs/components/native-select)



<ComponentPreview componentName="native-select" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/native-select
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Field](/docs/components/field)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/native-select.tsx" src="/native-select.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
NativeSelect
├── NativeSelectOption
└── NativeSelectOptGroup
    └── NativeSelectOption
```

## Usage [#usage]

```tsx
import { 
  NativeSelect, 
  NativeSelectOptGroup, 
  NativeSelectOption, 
} from "@/components/ui/native-select";
```

```tsx
<NativeSelect>
  <NativeSelectOptGroup label="Group 1">
    <NativeSelectOption value="1">Option 1</NativeSelectOption>
    <NativeSelectOption value="2">Option 2</NativeSelectOption>
    <NativeSelectOption value="3">Option 3</NativeSelectOption>
  </NativeSelectOptGroup>
</NativeSelect>
```

## Native Select vs Select [#native-select-vs-select]

* **NativeSelect** — Use for native browser behavior, better performance, or mobile-optimized dropdowns.
* **Select** — Use for custom styling, animations, or complex interactions.

## Sizes [#sizes]

Use the `size` prop to change the select height.

### Small [#small]

<ComponentPreview componentName="native-select" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="native-select" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="native-select" fileName="example-size-lg" />

## States [#states]

### Controlled [#controlled]

Use `value` and `onChange` to control the select externally.

<ComponentPreview componentName="native-select" fileName="example-controlled" />

### Disabled [#disabled]

Use the `disabled` prop to disable the select.

<ComponentPreview componentName="native-select" fileName="example-disabled" />

### Invalid [#invalid]

Use the `invalid` prop to mark the select as invalid.

<ComponentPreview componentName="native-select" fileName="example-invalid" />

## Examples [#examples]

### Groups [#groups]

Use `NativeSelectOptGroup` to group options with a label.

<ComponentPreview componentName="native-select" fileName="example-groups" />

### With Field [#with-field]

Wrap in `Field` with `FieldLabel` and `FieldDescription` for proper labeling and accessibility.

<ComponentPreview componentName="native-select" fileName="example-with-field" />

## API Reference [#api-reference]

### NativeSelect [#nativeselect]

Extends native `<select>` props. Additional props:

| Prop       | Type                   | Default |
| ---------- | ---------------------- | ------- |
| `size`     | `"sm" \| "md" \| "lg"` | `"md"`  |
| `disabled` | `boolean`              | -       |
| `invalid`  | `boolean`              | -       |

### NativeSelectOptGroup [#nativeselectoptgroup]

Extends native `<optgroup>` props. Use `label` for the group label.

### NativeSelectOption [#nativeselectoption]

Extends native `<option>` props. Use `value` and children for option value and label.

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/field#api-reference).


# Number Input (/docs/components/number-input)



<ComponentPreview componentName="number-input" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/number-input
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        , 

        [Field](/docs/components/field)

        , and 

        [Input](/docs/components/input)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/number-input.tsx" src="/number-input.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
NumberInput
└── NumberInputGroup
    ├── NumberInputDecrement
    ├── NumberInputInput
    ├── NumberInputIncrement
    └── NumberInputScrubber
```

## Usage [#usage]

```tsx
import { 
  NumberInput, 
  NumberInputGroup, 
  NumberInputInput, 
  NumberInputIncrement, 
  NumberInputDecrement 
} from "@/comopnents/ui/number-input";
```

```tsx showLineNumbers
<NumberInput>
  <NumberInputGroup>
    <NumberInputInput />
    <NumberInputIncrement />
    <NumberInputDecrement />
  </NumberInputGroup>
</NumberInput>
```

## Controlled [#controlled]

Use `value` and `onValueChange` to control the number input. Keep the value as a string when using `formatOptions` to preserve locale formatting.

<ComponentPreview componentName="number-input" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

Use the `disabled` prop to disable the number input.

<ComponentPreview componentName="number-input" fileName="example-disabled" />

### Invalid [#invalid]

Use the `invalid` prop to mark the number input as invalid.

<ComponentPreview componentName="number-input" fileName="example-invalid" />

## Sizes [#sizes]

Use the `size` prop to change the input height.

### Small [#small]

<ComponentPreview componentName="number-input" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="number-input" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="number-input" fileName="example-size-lg" />

## Examples [#examples]

### Field Only [#field-only]

<ComponentPreview componentName="number-input" fileName="example-field-only" />

### With Field [#with-field]

Use [Field](/docs/components/field) components for a labeled number input with helper text.

<ComponentPreview componentName="number-input" fileName="example-with-field" />

### With Input Group [#with-input-group]

Use `InputGroup`, `InputGroupAddon`, and `InputGroupText` to add prefix or suffix.

<ComponentPreview componentName="number-input" fileName="example-with-input-group" />

### With Scrub [#with-scrub]

Use the `NumberInputScrubber` to drag the label to change the value.

<ComponentPreview componentName="number-input" fileName="example-scrub" />

### With Range [#with-range]

Pass `min` and `max` to restrict the value to the specified range.

Use `clampValueOnBlur={false}` to allow typing outside range until blur.

<ComponentPreview componentName="number-input" fileName="example-range" />

### With Formatted Value [#with-formatted-value]

Use `formatOptions` with `Intl.NumberFormatOptions` to format the displayed value.

<ComponentPreview componentName="number-input" fileName="example-formatted" />

### With Step [#with-step]

Use the `step` prop to set the increment/decrement amount.

<ComponentPreview componentName="number-input" fileName="example-step" />

### Mouse Wheel [#mouse-wheel]

Use the `allowMouseWheel` prop to increment or decrement the value with the mouse wheel.

<ComponentPreview componentName="number-input" fileName="example-mouse-wheel" />

## API Reference [#api-reference]

### NumberInput [#numberinput]

Root component. Manages numeric value and stepper controls.

| Prop                 | Type                                    | Default                   |
| -------------------- | --------------------------------------- | ------------------------- |
| `size`               | `"sm" \| "md" \| "lg"`                  | `"md"`                    |
| `scrubber`           | `boolean`                               | `false`                   |
| `defaultValue`       | `string`                                | -                         |
| `value`              | `string`                                | -                         |
| `min`                | `number`                                | `Number.MIN_SAFE_INTEGER` |
| `max`                | `number`                                | `Number.MAX_SAFE_INTEGER` |
| `step`               | `number`                                | `1`                       |
| `formatOptions`      | `Intl.NumberFormatOptions`              | -                         |
| `disabled`           | `boolean`                               | -                         |
| `invalid`            | `boolean`                               | -                         |
| `focusInputOnChange` | `boolean`                               | `true`                    |
| `clampValueOnBlur`   | `boolean`                               | `true`                    |
| `allowMouseWheel`    | `boolean`                               | `false`                   |
| `onValueChange`      | `(details: ValueChangeDetails) => void` | -                         |
| `className`          | `string`                                | -                         |
| `asChild`            | `boolean`                               | `false`                   |

### NumberInputGroup [#numberinputgroup]

Wraps the input and increment/decrement buttons.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### NumberInputDecrement [#numberinputdecrement]

Decreases the value by the step amount.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### NumberInputIncrement [#numberinputincrement]

Increases the value by the step amount.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### NumberInputInput [#numberinputinput]

Numeric input. Accepts number or direct typing.

| Prop        | Type                   | Default |
| ----------- | ---------------------- | ------- |
| `size`      | `"sm" \| "md" \| "lg"` | `"md"`  |
| `className` | `string`               | -       |
| `asChild`   | `boolean`              | `false` |

### NumberInputScrubber [#numberinputscrubber]

Drag area for scrubbing the value.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/number-input#api-reference).


# Pagination (/docs/components/pagination)



<ComponentPreview componentName="pagination" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/pagination
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/pagination.tsx" src="/pagination.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Pagination
├── PaginationPrevious
├── PaginationItems
└── PaginationNext
```

## Usage [#usage]

```tsx
import {
  Pagination,
  PaginationItems,
  PaginationNext,
  PaginationPrevious,
} from "@/components/ui/pagination";
```

```tsx
<Pagination>
  <PaginationPrevious />
  <PaginationItems />
  <PaginationNext />
</Pagination>
```

## Controlled [#controlled]

Use `page` and `onPageChange` to control the current page.

<ComponentPreview componentName="pagination" fileName="example-controlled" />

## Examples [#examples]

### Page Range [#page-range]

Use `page` and `pageSize` properties to show which items are visible.

<ComponentPreview componentName="pagination" fileName="example-page-range" />

### With Links [#with-links]

> Under development

### Table [#table]

Use `Pagination` with `Table` to paginate a table.

<ComponentPreview componentName="pagination" fileName="example-table" />

## API Reference [#api-reference]

### Pagination [#pagination]

| Prop               | Type                                       | Default |
| ------------------ | ------------------------------------------ | ------- |
| `count`            | `number`                                   | -       |
| `page`             | `number`                                   | -       |
| `defaultPage`      | `number`                                   | `1`     |
| `pageSize`         | `number`                                   | -       |
| `defaultPageSize`  | `number`                                   | `10`    |
| `siblingCount`     | `number`                                   | `1`     |
| `onPageChange`     | `(details: PageChangeDetails) => void`     | -       |
| `onPageSizeChange` | `(details: PageSizeChangeDetails) => void` | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/pagination#api-reference).


# Password Input (/docs/components/password-input)



<ComponentPreview componentName="password-input" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/password-input
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Input Group](/docs/components/input-group)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/password-input.tsx" src="/password-input.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
PasswordInput
└── PasswordInputGroup
    ├── PasswordInputInput
    └── PasswordInputTrigger
```

## Usage [#usage]

```tsx
import {
  PasswordInput,
  PasswordInputGroup,
  PasswordInputInput,
  PasswordInputTrigger,
} from "@/components/ui/password-input";
```

```tsx showLineNumbers
<PasswordInput>
  <PasswordInputGroup>
    <PasswordInputInput placeholder="Enter password" />
    <PasswordInputTrigger />
  </PasswordInputGroup>
</PasswordInput>
```

## Controlled [#controlled]

Use `value` and `onChange` on `PasswordInputInput` to control the password value.

<ComponentPreview componentName="password-input" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

Use the `disabled` prop to disable the password input.

<ComponentPreview componentName="password-input" fileName="example-disabled" />

### Invalid [#invalid]

Use the `invalid` prop to mark the password input as invalid.

<ComponentPreview componentName="password-input" fileName="example-invalid" />

## Sizes [#sizes]

Use the `size` prop to change the input height.

### Small [#small]

<ComponentPreview componentName="password-input" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="password-input" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="password-input" fileName="example-size-lg" />

## Examples [#examples]

### Autocomplete [#autocomplete]

Use the `autoComplete` prop to hint autofill behavior to the browser.

* `current-password` — signing in with an existing password
* `new-password` — creating or resetting a password

<ComponentPreview componentName="password-input" fileName="example-autocomplete" />

### Controlled Visibility [#controlled-visibility]

Use `visible` and `onVisibilityChange` to control whether the value is shown.

<ComponentPreview componentName="password-input" fileName="example-controlled-visibility" />

### Auto Hide [#auto-hide]

Use `visible`, `onVisibilityChange`, and a timer to hide the password again after it is revealed.

<ComponentPreview componentName="password-input" fileName="example-auto-hide" />

### Custom Indicator [#custom-indicator]

<ComponentPreview componentName="password-input" fileName="example-custom-indicator" />

### With Field [#with-field]

Combine with [Field](/docs/components/field) components, for labeled password fields with helper text.

<ComponentPreview componentName="password-input" fileName="example-field" />

## API Reference [#api-reference]

### PasswordInput [#passwordinput]

Root component. Manages visibility and input state.

| Prop                     | Type                                         | Default              |
| ------------------------ | -------------------------------------------- | -------------------- |
| `size`                   | `"sm" \| "md" \| "lg"`                       | `"md"`               |
| `autoComplete`           | `"current-password" \| "new-password"`       | `"current-password"` |
| `defaultVisible`         | `boolean`                                    | `false`              |
| `visible`                | `boolean`                                    | -                    |
| `disabled`               | `boolean`                                    | -                    |
| `invalid`                | `boolean`                                    | -                    |
| `readOnly`               | `boolean`                                    | -                    |
| `required`               | `boolean`                                    | -                    |
| `name`                   | `string`                                     | -                    |
| `ignorePasswordManagers` | `boolean`                                    | -                    |
| `onVisibilityChange`     | `(details: VisibilityChangeDetails) => void` | -                    |
| `className`              | `string`                                     | -                    |
| `asChild`                | `boolean`                                    | `false`              |

### PasswordInputGroup [#passwordinputgroup]

Wraps the input and visibility trigger.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |

### PasswordInputInput [#passwordinputinput]

Password field.

| Prop        | Type                   | Default |
| ----------- | ---------------------- | ------- |
| `size`      | `"sm" \| "md" \| "lg"` | `"md"`  |
| `className` | `string`               | -       |
| `asChild`   | `boolean`              | `false` |

### PasswordInputTrigger [#passwordinputtrigger]

Button that toggles visibility.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### PasswordInputIndicator [#passwordinputindicator]

Renders different icons based on visibility. Use `fallback` for the hidden state and pass the visible-state icon as children.

| Prop        | Type              | Default          |
| ----------- | ----------------- | ---------------- |
| `fallback`  | `React.ReactNode` | `<EyeOffIcon />` |
| `children`  | `React.ReactNode` | `<EyeIcon />`    |
| `className` | `string`          | -                |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/password-input#api-reference).


# Popover (/docs/components/popover)



<ComponentPreview componentName="popover" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/popover
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

         and 

        [Scroll Area](/docs/components/scroll-area)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/popover.tsx" src="/popover.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Popover
├── PopoverTrigger
└── PopoverContent
    ├── PopoverHeader
    │   ├── PopoverTitle
    │   └── PopoverDescription
    ├── PopoverBody
    ├── PopoverFooter
    └── PopoverClose
```

## Usage [#usage]

```tsx
import { 
  Popover, 
  PopoverTrigger, 
  PopoverContent, 
  PopoverHeader,
  PopoverTitle, 
  PopoverDescription,
  PopoverBody,
  PopoverFooter,
  PopoverClose,
} from "@/components/ui/popover";
```

```tsx
<Popover>
  <PopoverTrigger />
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle />
      <PopoverDescription />
    </PopoverHeader>
    <PopoverBody>
      {/* Your content here */}
    </PopoverBody>
    <PopoverFooter>
      <PopoverClose />
    </PopoverFooter>
  </PopoverContent>
</Popover>
```

## Title & Description [#title--description]

`PopoverHeader` supports two usage patterns:

### Using props [#using-props]

Pass `title` and `description` props directly to `PopoverHeader`.

```tsx showLineNumbers
<PopoverHeader title="Popover Title" description="Popover description" />
```

> This approach does not require `PopoverTitle` or `PopoverDescription` components.

### Using components [#using-components]

Use `PopoverTitle` and `PopoverDescription` as children for more control.

```tsx showLineNumbers
<PopoverHeader>
  <PopoverTitle>Popover Title</PopoverTitle>
  <PopoverDescription>Popover description</PopoverDescription>
</PopoverHeader>
```

## Positioning [#positioning]

Control the position of the popover relative to the trigger using the `positioning` prop.

<ComponentPreview componentName="popover" fileName="example-positioning" />

## Examples [#examples]

### Non-modal [#non-modal]

To make the popover non-modal, set the `modal` prop to `false`.

<ComponentPreview componentName="popover" fileName="example-non-modal" />

### Nested [#nested]

Nest popovers within one another.

<ComponentPreview componentName="popover" fileName="example-nested" />

### Anchor [#anchor]

Use `PopoverAnchor` to position the popover relative to a different element than the trigger.

<ComponentPreview componentName="popover" fileName="example-anchor" />

### Close button [#close-button]

Use `showCloseButton` prop to show a close button in the top-right corner.

<ComponentPreview componentName="popover" fileName="example-close-button" />

### Close behavior [#close-behavior]

Use `closeOnInteractOutside` and `closeOnEscape` props to prevent closing on outside click and escape.

<ComponentPreview componentName="popover" fileName="example-close-behavior" />

### With Scroll [#with-scroll]

Use `PopoverBody` to make the content area scrollable while keeping header and footer fixed.

<ComponentPreview componentName="popover" fileName="example-scroll-area" />

### Inside dialog [#inside-dialog]

Render a popover inside a dialog.

<ComponentPreview componentName="popover" fileName="example-with-dialog" />

### Custom spacing [#custom-spacing]

Use `[--space:--spacing("value")]` on `PopoverContent` to adjust internal padding.

Default spacing is `--spacing(4)`.

<ComponentPreview componentName="popover" fileName="example-custom-spacing" />

> You can use breakpoint utilities to change the internal spacing at different screen sizes.

```css
  md:[--space:--spacing(6)] lg:[--space:--spacing(8)]
```

## API Reference [#api-reference]

### Popover [#popover]

Root element of the popover.

| Prop                     | Type                                   | Default |
| ------------------------ | -------------------------------------- | ------- |
| `open`                   | `boolean`                              | -       |
| `defaultOpen`            | `boolean`                              | -       |
| `onOpenChange`           | `(details: OpenChangeDetails) => void` | -       |
| `positioning`            | `PositioningOptions`                   | -       |
| `modal`                  | `boolean`                              | `true`  |
| `closeOnInteractOutside` | `boolean`                              | `true`  |
| `closeOnEscape`          | `boolean`                              | `true`  |

### PopoverTrigger [#popovertrigger]

Opens the popover on click. Use `asChild` for custom trigger elements.

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | -       |

### PopoverAnchor [#popoveranchor]

Element the popover is positioned relative to. Use when the reference is not the trigger.

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | -       |

### PopoverContent [#popovercontent]

Holds the popover panel content. Displayed in a portal.

| Prop              | Type      | Default |
| ----------------- | --------- | ------- |
| `showCloseButton` | `boolean` | `false` |
| `className`       | `string`  | -       |

| Attribute | Default        |
| --------- | -------------- |
| `--space` | `--spacing(4)` |

### PopoverHeader [#popoverheader]

Header container. Accepts `title` and `description` props or children.

| Prop          | Type     | Default |
| ------------- | -------- | ------- |
| `title`       | `string` | -       |
| `description` | `string` | -       |
| `className`   | `string` | -       |

### PopoverTitle [#popovertitle]

Accessible title for the popover panel.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | -       |

### PopoverDescription [#popoverdescription]

Accessible description for the popover panel.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | -       |

### PopoverBody [#popoverbody]

Scrollable content area. Uses [ScrollArea](/docs/components/scroll-area) for overflow.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### PopoverFooter [#popoverfooter]

Footer area for actions or secondary content.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### PopoverClose [#popoverclose]

Closes the popover on click. Use `asChild` for custom close elements.

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | -       |

### PopoverArrow [#popoverarrow]

Optional arrow pointing toward the trigger element.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

| Attribute            | Default                      |
| -------------------- | ---------------------------- |
| `--arrow-background` | `var(--popover)`             |
| `--arrow-size`       | `calc(1.5 * var(--spacing))` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/popover#api-reference).


# Progress (/docs/components/progress)



<ComponentPreview componentName="progress" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/progress
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Field](/docs/components/field)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Add the following animations to your 

        `globals.css`

        .
      </Step>

      ```css title="globals.css" showLineNumbers
      @theme inline {
        --animate-indeterminate: indeterminate 1.5s ease-in-out infinite;

        @keyframes indeterminate {
          0% { transform: translateX(-100%); }
          100% { transform: translateX(400%); }
        }
      }
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/progress.tsx" src="/progress.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Progress } from "@/components/ui/progress";
```

```tsx
<Progress value={50} />
```

## Controlled [#controlled]

Use `value` and to control the progress bar.

<ComponentPreview componentName="progress" fileName="example-controlled" />

## Orientation [#orientation]

Use the `orientation` prop to orient the progress bar horizontally or vertically.

### Horizontal [#horizontal]

<ComponentPreview componentName="progress" fileName="example-orientation-horizontal" />

### Vertical [#vertical]

<ComponentPreview componentName="progress" fileName="example-orientation-vertical" />

## Examples [#examples]

### With label [#with-label]

Use `ProgressValue` and `FieldLabel` to add a label to the progress bar.

<ComponentPreview componentName="progress" fileName="example-with-label" />

### Indeterminate [#indeterminate]

Use the `indeterminate` prop when the completion percentage is unknown.

<ComponentPreview componentName="progress" fileName="example-indeterminate" />

## API Reference [#api-reference]

### Progress [#progress]

Root element of the progress bar.

| Prop            | Type                                    | Default        |
| --------------- | --------------------------------------- | -------------- |
| `value`         | `number \| null`                        | -              |
| `defaultValue`  | `number`                                | -              |
| `onValueChange` | `(details: ValueChangeDetails) => void` | -              |
| `indeterminate` | `boolean`                               | `false`        |
| `min`           | `number`                                | `0`            |
| `max`           | `number`                                | `100`          |
| `orientation`   | `"horizontal" \| "vertical"`            | `"horizontal"` |
| `className`     | `string`                                | -              |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/progress-linear#api-reference).


# Prose (/docs/components/prose)



<ComponentPreview componentName="prose" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/prose
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Import the following CSS rules into your 

        `globals.css`
      </Step>

      <CodeCollapsibleWrapper>
        ```css
        .prose h1:not(.not-prose h1) {
          scroll-margin: calc(var(--spacing) * 20);
          font-size: var(--text-2xl);
          line-height: var(--text-2xl--line-height);
          font-weight: 800;
          letter-spacing: var(--tracking-tight);
        }

        .prose h2:not(.not-prose h2) {
          scroll-margin: calc(var(--spacing) * 20);
          padding-bottom: calc(var(--spacing) * 2);
          font-size: var(--text-xl);
          line-height: var(--text-xl--line-height);
          font-weight: 600;
          letter-spacing: var(--tracking-tight);
          margin-top: calc(var(--spacing) * 8);
        }

        .prose h2:not(.not-prose h2):first-child {
          margin-top: 0;
        }

        .prose h3:not(.not-prose h3) {
          scroll-margin: calc(var(--spacing) * 20);
          font-size: var(--text-lg);
          line-height: var(--text-lg--line-height);
          font-weight: 600;
          letter-spacing: var(--tracking-tight);
          margin-top: calc(var(--spacing) * 8);
        }

        .prose h3:not(.not-prose h3):first-child {
          margin-top: 0;
        }

        .prose h4:not(.not-prose h4) {
          scroll-margin: calc(var(--spacing) * 20);
          font-size: var(--text-xl);
          line-height: var(--text-xl--line-height);
          font-weight: 600;
          letter-spacing: var(--tracking-tight);
          margin-top: calc(var(--spacing) * 8);
        }

        .prose h4:not(.not-prose h4):first-child {
          margin-top: 0;
        }

        .prose h5:not(.not-prose h5) {
          scroll-margin: calc(var(--spacing) * 20);
          font-size: var(--text-lg);
          line-height: var(--text-lg--line-height);
          font-weight: 600;
          letter-spacing: var(--tracking-tight);
          margin-top: calc(var(--spacing) * 8);
        }

        .prose h5:not(.not-prose h5):first-child {
          margin-top: 0;
        }

        .prose h6:not(.not-prose h6) {
          scroll-margin: calc(var(--spacing) * 20);
          font-size: var(--text-base);
          line-height: var(--text-base--line-height);
          font-weight: 600;
          letter-spacing: var(--tracking-tight);
          margin-top: calc(var(--spacing) * 8);
        }

        .prose h6:not(.not-prose h6):first-child {
          margin-top: 0;
        }

        .prose h1:not(.not-prose h1) + p,
        .prose h2:not(.not-prose h2) + p,
        .prose h3:not(.not-prose h3) + p,
        .prose h4:not(.not-prose h4) + p,
        .prose h5:not(.not-prose h5) + p,
        .prose h6:not(.not-prose h6) + p {
          margin-top: 0;
        }

        .prose p:not(.not-prose p) {
          line-height: 1.75;
        }

        .prose p:not(.not-prose p):not(:first-child) {
          margin-top: calc(var(--spacing) * 6);
        }

        .prose li:not(.not-prose li) {
          line-height: 1.75;
        }

        .prose a:not(.not-prose a) {
          font-weight: 500;
          color: var(--color-primary);
          text-decoration: underline;
          text-underline-offset: var(--spacing);
        }

        .prose blockquote:not(.not-prose blockquote) {
          margin-top: calc(var(--spacing) * 6);
          border-left: 2px solid var(--color-border);
          padding-left: calc(var(--spacing) * 6);
          font-style: italic;
        }

        .prose table:not(.not-prose table) {
          margin-top: calc(var(--spacing) * 6);
          margin-bottom: calc(var(--spacing) * 6);
          width: 100%;
          overflow-y: auto;
        }

        .prose table:not(.not-prose table) thead tr {
          margin: 0;
          border-top: 1px solid var(--color-border);
          padding: 0;
        }

        .prose table:not(.not-prose table) thead tr:nth-child(even) {
          background-color: var(--color-muted);
        }

        .prose table:not(.not-prose table) th {
          border: 1px solid var(--color-border);
          padding: calc(var(--spacing) * 2) calc(var(--spacing) * 4);
          text-align: left;
          font-weight: 700;
        }

        .prose table:not(.not-prose table) th[align="center"] {
          text-align: center;
        }

        .prose table:not(.not-prose table) th[align="right"] {
          text-align: right;
        }
        .prose table:not(.not-prose table) tbody tr {
          margin: 0;
          border-top: 1px solid var(--color-border);
          padding: 0;
        }

        .prose table:not(.not-prose table) tbody tr:nth-child(even) {
          background-color: var(--color-muted);
        }

        .prose table:not(.not-prose table) td {
          border: 1px solid var(--color-border);
          padding: calc(var(--spacing) * 2) calc(var(--spacing) * 4);
          text-align: left;
        }

        .prose table:not(.not-prose table) td[align="center"] {
          text-align: center;
        }

        .prose table:not(.not-prose table) td[align="right"] {
          text-align: right;
        }

        .prose ul:not(.not-prose ul) {
          margin-top: calc(var(--spacing) * 6);
          margin-left: calc(var(--spacing) * 6);
          list-style: disc;
        }

        .prose ul:not(.not-prose ul) > li {
          margin-top: calc(var(--spacing) * 2);
        }

        .prose ul:not(.not-prose ul) p {
          margin-top: 0;
          margin-bottom: 0;
          display: inline;
        }

        .prose ol:not(.not-prose ol) {
          margin-top: calc(var(--spacing) * 6);
          margin-left: calc(var(--spacing) * 6);
          list-style: decimal;
        }

        .prose ol:not(.not-prose ol) > li {
          margin-top: calc(var(--spacing) * 2);
        }

        .prose ol:not(.not-prose ol) p {
          margin-top: 0;
          margin-bottom: 0;
          display: inline;
        }

        .prose .lead:not(.not-prose .lead) {
          font-size: var(--text-xl);
          line-height: var(--text-xl--line-height);
          color: var(--color-muted-foreground);
        }

        .prose .large:not(.not-prose .large) {
          font-size: var(--text-lg);
          line-height: var(--text-lg--line-height);
          font-weight: 600;
        }

        .prose .small:not(.not-prose .small) {
          font-size: var(--text-sm);
          line-height: 1;
          font-weight: 500;
        }

        .prose .muted:not(.not-prose .muted) {
          font-size: var(--text-sm);
          line-height: var(--text-sm--line-height);
          color: var(--color-muted-foreground);
        }

        .prose img:not(.not-prose img),
        .prose picture:not(.not-prose picture),
        .prose video:not(.not-prose video) {
          margin-top: calc(var(--spacing) * 6);
          margin-bottom: calc(var(--spacing) * 6);
        }

        .prose picture > img:not(.not-prose picture > img) {
          margin-top: 0;
          margin-bottom: 0;
        }

        .prose kbd:not(.not-prose kbd) {
          border-radius: calc(var(--radius) - 2px);
          background-color: var(--color-muted);
          padding: calc(var(--spacing) * 0.5) calc(var(--spacing) * 1.5);
          font-size: var(--text-xs);
          line-height: var(--text-xs--line-height);
          font-weight: 600;
        }

        .prose hr {
          margin-top: calc(var(--spacing) * 10);
          margin-bottom: calc(var(--spacing) * 10);
        }

        .prose dl:not(.not-prose dl) {
          margin-top: calc(var(--spacing) * 6);
          margin-bottom: calc(var(--spacing) * 6);
        }

        .prose dl:not(.not-prose dl) dt {
          font-weight: 600;
          margin-top: calc(var(--spacing) * 6);
          letter-spacing: var(--tracking-tight);
        }

        .prose dl:not(.not-prose dl) dt:first-child {
          margin-top: 0;
        }

        .prose details:not(.not-prose details) {
          margin-top: calc(var(--spacing) * 6);
        }

        .prose details:not(.not-prose details) summary {
          cursor: pointer;
          font-weight: 600;
          margin-top: calc(var(--spacing) * 6);
          letter-spacing: var(--tracking-tight);
        }

        .prose details:not(.not-prose details) p:first-of-type {
          margin-top: calc(var(--spacing) * 2);
        }

        .prose mark:not(.not-prose mark) {
          background-color: var(--color-yellow-300);
        }

        .prose small:not(.not-prose small) {
          font-size: var(--text-xs);
          line-height: 1;
        }
        ```
      </CodeCollapsibleWrapper>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/prose.tsx" src="/prose.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Prose } from "@/components/ui/prose";
```

```tsx
<Prose>
  <h1>Garlic bread with cheese: What the science tells us</h1>
  <p>
    For years parents have espoused the health benefits of eating garlic bread with cheese to their children, with the
    food earning such an iconic status in our culture that kids will often dress up as warm, cheesy loaf for Halloween.
  </p>
  <p>
    But a recent study shows that the celebrated appetizer may be linked to a series of rabies cases springing up around
    the country.
  </p>
</Prose>
```

## Undo prose styles [#undo-prose-styles]

Use the `not-prose` class in a child to exclude it from prose styles. Useful when using components to avoid unwanted styles.

<ComponentPreview componentName="prose" fileName="example-not-prose" />

## Examples [#examples]

### H1 [#h1]

<ComponentPreview componentName="prose" fileName="example-h1" />

### H2 [#h2]

<ComponentPreview componentName="prose" fileName="example-h2" />

### H3 [#h3]

<ComponentPreview componentName="prose" fileName="example-h3" />

### H4 [#h4]

<ComponentPreview componentName="prose" fileName="example-h4" />

### H5 [#h5]

<ComponentPreview componentName="prose" fileName="example-h5" />

### H6 [#h6]

<ComponentPreview componentName="prose" fileName="example-h6" />

### Paragraph [#paragraph]

<ComponentPreview componentName="prose" fileName="example-p" />

### Blockquote [#blockquote]

<ComponentPreview componentName="prose" fileName="example-blockquote" />

### Table [#table]

<ComponentPreview componentName="prose" fileName="example-table" />

### List [#list]

<ComponentPreview componentName="prose" fileName="example-list" />

### Ordered list [#ordered-list]

<ComponentPreview componentName="prose" fileName="example-ol" />

### Link [#link]

<ComponentPreview componentName="prose" fileName="example-a" />

### Media [#media]

<ComponentPreview componentName="prose" fileName="example-media" />

### Kbd [#kbd]

<ComponentPreview componentName="prose" fileName="example-kbd" />

### Inline code [#inline-code]

<ComponentPreview componentName="prose" fileName="example-inline-code" />

### Separator [#separator]

<ComponentPreview componentName="prose" fileName="example-separator" />

### Definition list [#definition-list]

<ComponentPreview componentName="prose" fileName="example-dl" />

### Details [#details]

<ComponentPreview componentName="prose" fileName="example-details" />

### Mark [#mark]

<ComponentPreview componentName="prose" fileName="example-mark" />

### Small [#small]

<ComponentPreview componentName="prose" fileName="example-small" />

## API Reference [#api-reference]

### Prose [#prose]

Root wrapper for typography-styled content.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | `false` |


# QR Code (/docs/components/qr-code)



<ComponentPreview componentName="qr-code" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/qr-code
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/qr-code.tsx" src="/qr-code.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
QrCode
├── QrCodeFrame
├── QrCodeOverlay
└── QrCodeDownload
```

## Usage [#usage]

```tsx
import { 
  QrCode, 
  QrCodeFrame,
  QrCodeOverlay,
  QrCodeDownload,
} from "@/components/ui/qr-code";
```

```tsx
<QrCode>
  <QrCodeFrame />
  <QrCodeOverlay />
  <QrCodeDownload />
</QrCode>
```

## Size [#size]

Override the size with the `--qr-code-size` CSS variable on `QrCode`

For example, `--qr-code-size:6rem` for small, `--qr-code-size:10rem` for large

<ComponentPreview componentName="qr-code" fileName="example-size" />

## Examples [#examples]

### With an overlay [#with-an-overlay]

Use `QrCodeOverlay` to add an overlay in the center.

<ComponentPreview componentName="qr-code" fileName="example-overlay" />

### Error correction [#error-correction]

In cases where the link is too long or the logo overlay covers a significant area, the error correction level can be increased.

Use the `encoding.ecc` property to set the error correction level:

* **L:** Allows recovery of up to 7% data loss (default)
* **M:** Allows recovery of up to 15% data loss
* **Q:** Allows recovery of up to 25% data loss
* **H:** Allows recovery of up to 30% data loss

<ComponentPreview componentName="qr-code" fileName="example-error-correction" />

### Download [#download]

Use `QrCodeDownload` with `fileName` and `mimeType` to let users download the QR code as an image.

<ComponentPreview componentName="qr-code" fileName="example-download" />

## API Reference [#api-reference]

### QrCode [#qrcode]

Root wrapper for the QR code and optional overlay/actions.

| Prop            | Type                                    | Default |
| --------------- | --------------------------------------- | ------- |
| `value`         | `string`                                | -       |
| `defaultValue`  | `string`                                | -       |
| `onValueChange` | `(details: ValueChangeDetails) => void` | -       |
| `encoding`      | `QrCodeGenerateOptions`                 | -       |
| `pixelSize`     | `number`                                | -       |
| `className`     | `string`                                | -       |
| `asChild`       | `boolean`                               | -       |

| Attribute                | Default                       |
| ------------------------ | ----------------------------- |
| `--qr-code-size`         | `--spacing(32)`               |
| `--qr-code-overlay-size` | `calc(var(--qr-code-size)/4)` |

### QrCodeFrame [#qrcodeframe]

SVG containing the QR pattern. Scales with size.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### QrCodeOverlay [#qrcodeoverlay]

Optional center overlay on top of the QR pattern.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### QrCodeDownload [#qrcodedownload]

Downloads the QR code as an image file.

| Prop        | Type          | Default |
| ----------- | ------------- | ------- |
| `fileName`  | `string`      | -       |
| `mimeType`  | `DataUrlType` | -       |
| `quality`   | `number`      | -       |
| `className` | `string`      | -       |
| `asChild`   | `boolean`     | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/qr-code#api-reference).


# Radio Group (/docs/components/radio-group)



<ComponentPreview componentName="radio-group" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/radio-group
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Field](/docs/components/field)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/radio-group.tsx" src="/radio-group.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
RadioGroup
└── RadioGroupItem
```

## Usage [#usage]

```tsx
import {
  RadioGroup,
  RadioGroupItem,
} from "@/components/ui/radio-group";
```

```tsx
<RadioGroup>
  <RadioGroupItem value="item-1">{/* label */}</RadioGroupItem>
  <RadioGroupItem value="item-2">{/* label */}</RadioGroupItem>
</RadioGroup>
```

## Controlled [#controlled]

Use the `value` and `onValueChange` props to control the radio group.

<ComponentPreview componentName="radio-group" fileName="example-controlled" />

## States [#states]

### Invalid [#invalid]

Use the `invalid` prop on `RadioGroup` to indicate an invalid state.

<ComponentPreview componentName="radio-group" fileName="example-invalid" />

### Disabled [#disabled]

Use the `disabled` on `RadioGroup` to disable  all the radio group items or on `RadioGroupItem` to disable a single item.

<ComponentPreview componentName="radio-group" fileName="example-disabled" />

## Examples [#examples]

### With Description [#with-description]

Use `FieldDescription` to add a description to the radio group.

<ComponentPreview componentName="radio-group" fileName="example-with-description" />

### Card Style [#card-style]

Use `FieldLabel` to wrap the entire `Field` for a clickable card-style selection.

<ComponentPreview componentName="radio-group" fileName="example-card" />

## API Reference [#api-reference]

### RadioGroup [#radiogroup]

Root component. Manages single selection from options.

| Prop            | Type                                    | Default |
| --------------- | --------------------------------------- | ------- |
| `value`         | `string`                                | `-`     |
| `defaultValue`  | `string`                                | `-`     |
| `disabled`      | `boolean`                               | `false` |
| `name`          | `string`                                | `-`     |
| `onValueChange` | `(details: ValueChangeDetails) => void` | `-`     |
| `className`     | `string`                                | `-`     |

### RadioGroupItem [#radiogroupitem]

Single radio option. Use `value` for selection.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `value`     | `string`  | `-`     |
| `disabled`  | `boolean` | `false` |
| `invalid`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/radio-group#api-reference).


# Rating (/docs/components/rating)



<ComponentPreview componentName="rating" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/rating
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Import the following variables into your CSS file
      </Step>

      <CodeCollapsibleWrapper>
        ```css
        @theme inline {
          --color-destructive-foreground: var(--destructive-foreground);
          --color-info: var(--info);
          --color-info-foreground: var(--info-foreground);
          --color-success: var(--success);
          --color-success-foreground: var(--success-foreground);
          --color-warning: var(--warning);
          --color-warning-foreground: var(--warning-foreground);
        }

        :root {
          --destructive-foreground: var(--color-red-700);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-700);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-700);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-700);
        }

        .dark {
          --destructive-foreground: var(--color-red-400);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-400);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-400);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-400);
        }
        ```
      </CodeCollapsibleWrapper>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/rating.tsx" src="/rating.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { RatingGroup } from "@/components/ui/rating";
```

```tsx
<RatingGroup />
```

## Controlled [#controlled]

Use `value` and `onValueChange` to control the rating programmatically.

<ComponentPreview componentName="rating" fileName="example-controlled" />

## States [#states]

### Readonly [#readonly]

Use the `readOnly` prop to display a rating without interaction.

<ComponentPreview componentName="rating" fileName="example-readonly" />

### Disabled [#disabled]

Use the `disabled` prop to prevent interaction and show a disabled state.

<ComponentPreview componentName="rating" fileName="example-disabled" />

## Examples [#examples]

### Half star [#half-star]

Use `allowHalf` to allow half-star selections.

<ComponentPreview componentName="rating" fileName="example-half-star" />

### Count [#count]

Use the `count` prop to show more or less stars.

<ComponentPreview componentName="rating" fileName="example-count" />

### Testimonial [#testimonial]

Display a read-only rating inside a testimonial card.

<ComponentPreview componentName="rating" fileName="example-testimonial" />

### Customize size [#customize-size]

Use the `className` prop to set the size of the rating.

<ComponentPreview componentName="rating" fileName="example-custom-size" />

### Custom icon [#custom-icon]

Compose the rating with a different icon.

<ComponentPreview componentName="rating" fileName="example-custom-icon" />

### Custom color [#custom-color]

Override the filled color with `className`.

<ComponentPreview componentName="rating" fileName="example-custom-color" />

## API Reference [#api-reference]

### Rating [#rating]

Root component.

| Prop            | Type                                    | Default |
| --------------- | --------------------------------------- | ------- |
| `allowHalf`     | `boolean`                               | `false` |
| `count`         | `number`                                | `5`     |
| `defaultValue`  | `number`                                | `-`     |
| `value`         | `number`                                | `-`     |
| `onValueChange` | `(details: ValueChangeDetails) => void` | `-`     |
| `readOnly`      | `boolean`                               | `-`     |
| `disabled`      | `boolean`                               | `-`     |
| `className`     | `string`                                | `-`     |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/rating-group#api-reference).


# Resizable (/docs/components/resizable)



<ComponentPreview componentName="resizable" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/resizable
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/resizable.tsx" src="/resizable.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Resizable
├── ResizablePanel
└── ResizableResizeTrigger
```

## Usage [#usage]

```tsx
import {
  Resizable,
  ResizablePanel,
  ResizableResizeTrigger,
} from "@/components/ui/resizable";
```

```tsx
<Resizable>
  <ResizablePanel id="1" />
  <ResizableResizeTrigger id="1:2" />
  <ResizablePanel id="2" />
</Resizable>
```

## Orientation [#orientation]

Use the `orientation` prop to control the orientation of the resizable panels.

### Horizontal [#horizontal]

Set `orientation="horizontal"` to place panels side by side (default).

<ComponentPreview componentName="resizable" fileName="example-orientation-horizontal" />

### Vertical [#vertical]

Set `orientation="vertical"` to stack panels vertically.

<ComponentPreview componentName="resizable" fileName="example-orientation-vertical" />

## Examples [#examples]

### Handle [#handle]

Use the `withHandle` prop on `ResizableResizeTrigger` to show a visible grip handle for resizing.

<ComponentPreview componentName="resizable" fileName="example-handle" />

### Min / Max Size [#min--max-size]

Use `panels` with `minSize` and `maxSize` to constrain how small or large a panel can be resized.

<ComponentPreview componentName="resizable" fileName="example-min-max" />

### Multiple Panels [#multiple-panels]

<ComponentPreview componentName="resizable" fileName="example-multiple-panels" />

## API Reference [#api-reference]

### Resizable [#resizable]

Root component. Manages resizable panel layout.

| Prop               | Type                                       | Default        |
| ------------------ | ------------------------------------------ | -------------- |
| `panels`           | `PanelData[]`                              | -              |
| `defaultSize`      | `number[]`                                 | -              |
| `size`             | `number[]`                                 | -              |
| `orientation`      | `"horizontal" \| "vertical"`               | `"horizontal"` |
| `keyboardResizeBy` | `number`                                   | -              |
| `onResize`         | `(details: ResizeDetails) => void`         | -              |
| `onResizeStart`    | `() => void`                               | -              |
| `onResizeEnd`      | `(details: ResizeEndDetails) => void`      | -              |
| `onCollapse`       | `(details: ExpandCollapseDetails) => void` | -              |
| `onExpand`         | `(details: ExpandCollapseDetails) => void` | -              |
| `className`        | `string`                                   | -              |

### ResizablePanel [#resizablepanel]

A resizable panel. Multiple panels share the available space.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `id`        | `string`  | -       |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | -       |

### ResizableResizeTrigger [#resizableresizetrigger]

Draggable handle between panels for resizing.

| Prop         | Type                  | Default |
| ------------ | --------------------- | ------- |
| `id`         | `${string}:${string}` | -       |
| `withHandle` | `boolean`             | `false` |
| `disabled`   | `boolean`             | -       |
| `asChild`    | `boolean`             | `false` |
| `className`  | `string`              | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/splitter#api-reference).


# Scroll Area (/docs/components/scroll-area)



<ComponentPreview componentName="scroll-area" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/scroll-area
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/scroll-area.tsx" src="/scroll-area.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { ScrollArea } from "@/components/ui/scroll-area";
```

```tsx
<ScrollArea className="h-64">
  {/* Your content here */}
</ScrollArea>
```

## Examples [#examples]

### Scroll Fade [#scroll-fade]

Use `scrollFade` to add a subtle fade effect to the edges of the scroll area.

<ComponentPreview componentName="scroll-area" fileName="example-scroll-fade" />

### Horizontal Scroll [#horizontal-scroll]

<ComponentPreview componentName="scroll-area" fileName="example-horizontal" />

### Both Scrollbars [#both-scrollbars]

<ComponentPreview componentName="scroll-area" fileName="example-both-directions" />

### Nested [#nested]

Scroll areas can be nested within each other for complex layouts.

<ComponentPreview componentName="scroll-area" fileName="example-nested" />

## API Reference [#api-reference]

### ScrollArea [#scrollarea]

Custom-styled scrollable region. Hides native scrollbars; preserves scroll behavior.

| Prop       | Type      | Default |
| ---------- | --------- | ------- |
| scrollFade | `boolean` | `false` |

| Attribute     | Default  |
| ------------- | -------- |
| `--fade-size` | `1.5rem` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/scroll-area#api-reference).


# Segment Group (/docs/components/segment-group)



<ComponentPreview componentName="segment-group" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/segment-group
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/segment-group.tsx" src="/segment-group.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
SegmentGroup
└── SegmentGroupItem
    └── SegmentGroupItemText
```

## Usage [#usage]

```tsx
import {
  SegmentGroup,
  SegmentGroupIndicator,
  SegmentGroupItem,
  SegmentGroupItemText,
} from "@/components/ui/segment-group";
```

```tsx
<SegmentGroup>
  <SegmentGroupIndicator />
  <SegmentGroupItem value="profile">
    <SegmentGroupItemText />
  </SegmentGroupItem>
  <SegmentGroupItem value="account">
    <SegmentGroupItemText />
  </SegmentGroupItem>
</SegmentGroup>
```

## Controlled [#controlled]

Control the selected value programmatically with `value` and `onValueChange` props.

<ComponentPreview componentName="segment-group" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

Use the `disabled` prop to disable the entire segment group.

<ComponentPreview componentName="segment-group" fileName="example-disabled" />

### Disabled Item [#disabled-item]

Use the `disabled` prop on individual items to disable specific options.

<ComponentPreview componentName="segment-group" fileName="example-disabled-item" />

## Variant [#variant]

### Default [#default]

<ComponentPreview componentName="segment-group" fileName="example-default" />

### Underline [#underline]

<ComponentPreview componentName="segment-group" fileName="example-variant-underline" />

## Orientation [#orientation]

Use `orientation` to change the direction of the items.

### Horizontal [#horizontal]

<ComponentPreview componentName="segment-group" fileName="example-orientation-horizontal" />

### Vertical [#vertical]

<ComponentPreview componentName="segment-group" fileName="example-orientation-vertical" />

### Vertical with Underline [#vertical-with-underline]

<ComponentPreview componentName="segment-group" fileName="example-variant-underline-orientation-vertical" />

## Examples [#examples]

### Indicator on Hover [#indicator-on-hover]

The indicator follows the mouse and returns to the selected item when not hovering.

<ComponentPreview componentName="segment-group" fileName="example-indicator-on-hover" />

### Custom Indicator [#custom-indicator]

Use `*:data-[slot=segment-group-indicator]:bg-*` classes to change the color of the indicator.

<ComponentPreview componentName="segment-group" fileName="example-custom-indicator" />

## API Reference [#api-reference]

### SegmentGroup [#segmentgroup]

Root component. Manages segmented control state (single or multi-select).

| Prop            | Type                                    | Default        |
| --------------- | --------------------------------------- | -------------- |
| `defaultValue`  | `string`                                | -              |
| `value`         | `string`                                | -              |
| `onValueChange` | `(details: ValueChangeDetails) => void` | -              |
| `orientation`   | `"horizontal" \| "vertical"`            | `"horizontal"` |
| `variant`       | `"default" \| "underline"`              | `"default"`    |
| `disabled`      | `boolean`                               | -              |
| `className`     | `string`                                | -              |
| `asChild`       | `boolean`                               | -              |

### SegmentGroupIndicator [#segmentgroupindicator]

Visual indicator that moves to the selected segment(s).

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | -       |
| `className` | `string`  | -       |

### SegmentGroupItem [#segmentgroupitem]

Single segment option. Use `value` for selection.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `value`     | `string`  | -       |
| `disabled`  | `boolean` | -       |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### SegmentGroupItemText [#segmentgroupitemtext]

Text label for a segment. Often wraps icon + text.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/segment-group#api-reference).


# Select (/docs/components/select)



<ComponentPreview componentName="select" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/select
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Separator](/docs/components/separator)

         and 

        [Input](/docs/components/input)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/select.tsx" src="/select.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Select
├── SelectTrigger
│   └── SelectValue
└── SelectContent
    ├── SelectEmpty
    ├── SelectClearTrigger
    ├── SelectGroup
    │   ├── SelectGroupLabel
    │   └── SelectItem
    └── SelectItem
```

## Usage [#usage]

```tsx
import { createListCollection } from "@ark-ui/react";
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select";
```

```tsx
const collection = createListCollection({
  items: ["Option 1", "Option 2", "Option 3"],
});

<Select collection={collection}>
  <SelectTrigger>
    <SelectValue placeholder="Select an option" />
  </SelectTrigger>
  <SelectContent>
    {collection.items.map((item) => (
      <SelectItem item={item} key={item}>
        {item}
      </SelectItem>
    ))}
  </SelectContent>
</Select>
```

## Controlled [#controlled]

Use `value` and `onValueChange` to control the selected items.

<ComponentPreview componentName="select" fileName="example-controlled" />

## Size [#size]

Control trigger size with the `size` prop on SelectTrigger.

### Small [#small]

<ComponentPreview componentName="select" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="select" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="select" fileName="example-size-lg" />

## States [#states]

### Disabled [#disabled]

<ComponentPreview componentName="select" fileName="example-disabled" />

### Invalid [#invalid]

<ComponentPreview componentName="select" fileName="example-invalid" />

## Examples [#examples]

### Multiple [#multiple]

Enable multiple selection with the `multiple` prop.

<ComponentPreview componentName="select" fileName="example-multiple" />

### Grouping [#grouping]

Organize options into groups using `groupBy` and `SelectGroup`.

<ComponentPreview componentName="select" fileName="example-grouping" />

### With Field [#with-field]

Use `Field` for labels, helper text, and error handling.

<ComponentPreview componentName="select" fileName="example-with-field" />

### Max Selection [#max-selection]

<ComponentPreview componentName="select" fileName="example-max-selection" />

### With Scroll [#with-scroll]

<ComponentPreview componentName="select" fileName="example-with-scroll" />

### Empty [#empty]

Use `SelectEmpty` to display a message when the collection has no items.

<ComponentPreview componentName="select" fileName="example-empty" />

## API Reference [#api-reference]

### Select [#select]

Root component.

| Prop            | Type                                       | Default |
| --------------- | ------------------------------------------ | ------- |
| `collection`    | `ListCollection<T>`                        | -       |
| `value`         | `string[]`                                 | -       |
| `defaultValue`  | `string[]`                                 | -       |
| `onValueChange` | `(details: ValueChangeDetails<T>) => void` | -       |
| `multiple`      | `boolean`                                  | `false` |
| `disabled`      | `boolean`                                  | -       |
| `invalid`       | `boolean`                                  | -       |
| `name`          | `string`                                   | -       |
| `required`      | `boolean`                                  | -       |
| `positioning`   | `PositioningOptions`                       | -       |
| `lazyMount`     | `boolean`                                  | `true`  |
| `unmountOnExit` | `boolean`                                  | `true`  |
| `className`     | `string`                                   | -       |

### SelectTrigger [#selecttrigger]

Opens the dropdown on click. Displays the selected value or placeholder.

| Prop        | Type                   | Default |
| ----------- | ---------------------- | ------- |
| `size`      | `"sm" \| "md" \| "lg"` | `"md"`  |
| `showClear` | `boolean`              | `false` |
| `className` | `string`               | -       |
| `asChild`   | `boolean`              | -       |

### SelectValue [#selectvalue]

Shows the selected value or placeholder. Use `SelectContext` as children for custom display.

| Prop          | Type      | Default |
| ------------- | --------- | ------- |
| `placeholder` | `string`  | -       |
| `className`   | `string`  | -       |
| `asChild`     | `boolean` | -       |

### SelectContent [#selectcontent]

Holds the dropdown options. Displayed in a portal.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### SelectClearTrigger [#selectcleartrigger]

Button to clear the selected value. Shown when `showClear` is true on `SelectTrigger`.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### SelectGroup [#selectgroup]

Groups related options under an optional heading.

| Prop        | Type                    | Default |
| ----------- | ----------------------- | ------- |
| `heading`   | `string` \| `ReactNode` | -       |
| `className` | `string`                | -       |
| `asChild`   | `boolean`               | -       |

### SelectGroupLabel [#selectgrouplabel]

Label for an option group.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### SelectItem [#selectitem]

A single selectable option in the dropdown.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `item`      | `T`       | -       |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### SelectEmpty [#selectempty]

Shown when the collection has no items (`collection.size === 0`). Place inside `SelectContent`.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/select#api-reference).


# Separator (/docs/components/separator)



<ComponentPreview componentName="separator" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/separator
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/separator.tsx" src="/separator.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Separator } from "@/components/ui/separator";
```

```tsx
<Separator />
```

## Examples [#examples]

### Vertical [#vertical]

Use `orientation` prop to control the orientation of the separator.

<ComponentPreview componentName="separator" fileName="example-vertical" />

### Menu [#menu]

<ComponentPreview componentName="separator" fileName="example-menu" />

### List [#list]

<ComponentPreview componentName="separator" fileName="example-list" />

## API Reference [#api-reference]

### Separator [#separator]

Horizontal or vertical divider between content.

| Prop          | Type                         | Default        |
| ------------- | ---------------------------- | -------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
| `className`   | `string`                     | `-`            |

***

For complete list of props, see [Ark UI documentation](https://ark-ui.com/docs/components/separator#api-reference).


# Sheet (/docs/components/sheet)



<ComponentPreview componentName="sheet" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/sheet
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

         and 

        [Dialog](/docs/components/dialog)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/sheet.tsx" src="/sheet.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Sheet
├── SheetTrigger
└── SheetContent
    ├── SheetHeader
    │   ├── SheetTitle
    │   └── SheetDescription
    ├── SheetBody
    └── SheetFooter
        └── SheetClose
```

## Usage [#usage]

```tsx
import { 
  Sheet, 
  SheetContent, 
  SheetDescription, 
  SheetHeader, 
  SheetTitle, 
  SheetTrigger 
} from "@/components/ui/sheet";
```

```tsx
<Sheet>
  <SheetTrigger>Open</SheetTrigger>
  <SheetContent>
    <SheetHeader>
      <SheetTitle>Sheet Title</SheetTitle>     
      <SheetDescription>Sheet Description</SheetDescription>
    </SheetHeader>
  </SheetContent>
</Sheet>
```

## Sides [#sides]

Control which side the sheet slides in from using the `side` prop.

<ComponentPreview componentName="sheet" fileName="example-sides" />

## Examples [#examples]

### Inset Variant [#inset-variant]

Use the `variant="inset"` prop to add padding. The sheet appears as a floating card rather than edge-to-edge.

<ComponentPreview componentName="sheet" fileName="example-inset" />

### With Scroll [#with-scroll]

Use `SheetBody` to make the content area scrollable while keeping header and footer fixed.

<ComponentPreview componentName="sheet" fileName="example-scroll-area" />

### No Close Button [#no-close-button]

Use the `showCloseButton` prop to hide the close button in the top right corner.

<ComponentPreview componentName="sheet" fileName="example-no-close-button" />

### Close behavior [#close-behavior]

Use `closeOnInteractOutside` and `closeOnEscape` props to prevent closing on outside click and escape.

<ComponentPreview componentName="sheet" fileName="example-close-behavior" />

### Non-Modal [#non-modal]

Use `modal={false}` to allow interaction with elements outside the sheet. Disables focus trapping and scroll prevention.

<ComponentPreview componentName="sheet" fileName="example-non-modal" />

### Custom spacing [#custom-spacing]

Use `[--space:--spacing("value")]` on `SheetContent` to adjust internal padding.

Default spacing is `--spacing(6)`.

<ComponentPreview componentName="sheet" fileName="example-custom-spacing" />

> You can use breakpoint utilities to change the internal spacing at different screen sizes.

```css
  md:[--space:--spacing(6)] lg:[--space:--spacing(8)]
```

## API Reference [#api-reference]

### Sheet [#sheet]

Root component. Uses Ark UI Dialog. Controls open state and slide direction.

| Prop                     | Type                                    | Default |
| ------------------------ | --------------------------------------- | ------- |
| `open`                   | `boolean`                               | `-`     |
| `defaultOpen`            | `boolean`                               | `false` |
| `onOpenChange`           | `({ open }: OpenChangeDetails) => void` | `-`     |
| `modal`                  | `boolean`                               | `true`  |
| `closeOnEscape`          | `boolean`                               | `true`  |
| `closeOnInteractOutside` | `boolean`                               | `true`  |
| `initialFocusEl`         | `() => MaybeElement`                    | `-`     |
| `finalFocusEl`           | `() => MaybeElement`                    | `-`     |
| `onEscapeKeyDown`        | `(event: KeyboardEvent) => void`        | `-`     |
| `onInteractOutside`      | `(event: InteractOutsideEvent) => void` | `-`     |
| `className`              | `string`                                | `-`     |

### SheetTrigger [#sheettrigger]

Opens the sheet on click. Use `asChild` for custom triggers.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

### SheetContent [#sheetcontent]

Holds the sheet panel. Slides in from the configured edge.

| Prop              | Type                                     | Default     |
| ----------------- | ---------------------------------------- | ----------- |
| `side`            | `"right" \| "left" \| "top" \| "bottom"` | `"right"`   |
| `variant`         | `"default" \| "inset"`                   | `"default"` |
| `showCloseButton` | `boolean`                                | `true`      |
| `className`       | `string`                                 | `-`         |

| Attribute | Default        |
| --------- | -------------- |
| `--space` | `--spacing(6)` |

### SheetHeader [#sheetheader]

Header area for title and description.

| Prop          | Type     | Default |
| ------------- | -------- | ------- |
| `title`       | `string` | `-`     |
| `description` | `string` | `-`     |
| `className`   | `string` | `-`     |

### SheetBody [#sheetbody]

Scrollable body content. Uses [ScrollArea](/docs/components/scroll-area) for overflow.

| Prop         | Type      | Default |
| ------------ | --------- | ------- |
| `scrollFade` | `boolean` | `false` |
| `className`  | `string`  | `-`     |

### SheetFooter [#sheetfooter]

Footer area for action buttons.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### SheetTitle [#sheettitle]

Accessible title. Announced to screen readers.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

### SheetDescription [#sheetdescription]

Accessible description. Announced to screen readers.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

### SheetClose [#sheetclose]

Closes the sheet on click.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | `-`     |

### SheetOverlay [#sheetoverlay]

Dimmed overlay behind the sheet.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | `-`     |

### SheetPositioner [#sheetpositioner]

Positioning wrapper for sheet content. Used internally; expose for custom layouts.

| Prop        | Type                                     | Default     |
| ----------- | ---------------------------------------- | ----------- |
| `side`      | `"right" \| "left" \| "top" \| "bottom"` | `-`         |
| `variant`   | `"default" \| "inset"`                   | `"default"` |
| `className` | `string`                                 | `-`         |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/dialog#api-reference).


# Sidebar (/docs/components/sidebar)





<PreviewIframe src="/view/blocks/sidebar/default" title="Sidebar Default" className="min-h-[550px]" />

For full-page examples that wire the sidebar:

Browse the Sidebar Components (soon).

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/sidebar
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        , 

        [Input](/docs/components/input)

        , 

        [Scroll Area](/docs/components/scroll-area)

        , 

        [Separator](/docs/components/separator)

        , 

        [Sheet](/docs/components/sheet)

        , 

        [Skeleton](/docs/components/skeleton)

        , 

        [Tooltip](/docs/components/tooltip)

        , and 

        [useIsMobile](/docs/components/use-is-mobile)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/sidebar.tsx" src="/sidebar.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
SidebarProvider
├── Sidebar
│   ├── SidebarHeader
│   ├── SidebarContent
│   │   └── SidebarGroup
│   │       ├── SidebarGroupLabel
│   │       ├── SidebarGroupAction
│   │       ├── SidebarGroupContent
│   │       └── SidebarMenu
│   │           ├── SidebarMenuItem
│   │           │   ├── SidebarMenuButton
│   │           │   ├── SidebarMenuAction
│   │           │   └── SidebarMenuBadge
│   │           └── SidebarMenuSub
│   │               ├── SidebarMenuSubButton
│   │               └── SidebarMenuSubItem
│   ├── SidebarFooter
│   ├── SidebarSeparator
│   └── SidebarInput
├── SidebarTrigger
├── SidebarRail
└── SidebarInset
```

## Structure [#structure]

Piecing a `Sidebar` together usually means:

* `<SidebarProvider>` — Owns open/collapsed state, mobile sheet state, and keyboard shortcut handling.
* `<Sidebar>` — Fixed (or sheet) column: `placement`, `variant`, and `collapsible` behavior.
* `<SidebarHeader>` / `<SidebarFooter>` — Pin content to the top or bottom of the column.
* `<SidebarContent>` — Scrollable middle; optional `scrollFade` on the inner scroll area.
* `<SidebarGroup>` — Labeled section inside the scroll region.
* `<SidebarTrigger>` — Icon/control wired to `useSidebar().toggleSidebar`.
* `<SidebarInset>` — Main document column beside the sidebar (required for `variant="inset"`).

Optional helpers: `<SidebarRail>` (edge hit target), the `<SidebarMenu>` building blocks (submenus, badges, skeletons, actions)—same roles as in the upstream doc.

<SidebarAnatomy title="Sidebar Anatomy" />

## Usage [#usage]

`app/layout.tsx` keeps the provider at the top level:

```tsx title="app/layout.tsx"
import { SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar";
import { AppSidebar } from "@/components/app-sidebar";

export default function Layout({ children }: React.PropsWithChildren) {
  return (
    <SidebarProvider>
      <AppSidebar />
      <main>
        <SidebarTrigger />
        {children}
      </main>
    </SidebarProvider>
  );
}
```

The sidebar column itself is usually a dedicated module:

```tsx title="components/app-sidebar.tsx"
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarHeader,
} from "@/components/ui/sidebar";

export function AppSidebar() {
  return (
    <Sidebar>
      <SidebarHeader />
      <SidebarContent>
        <SidebarGroup />
        <SidebarGroup />
      </SidebarContent>
      <SidebarFooter />
    </Sidebar>
  );
}
```

## Controlled [#controlled]

Use the `onOpenChange` prop to control the sidebar open state.

```tsx
"use client";

import React from "react";
import { Sidebar, SidebarProvider } from "@/components/ui/sidebar";

export const ControlledLayout = () => {
  const [open, setOpen] = React.useState(false);

  return (
    <SidebarProvider onOpenChange={setOpen} open={open}>
      <Sidebar />
    </SidebarProvider>
  );
}
```

## Theming [#theming]

Sidebar uses CSS variables to style the sidebar. See the full palette in [Colors](/docs/colors).

### Variable Reference [#variable-reference]

* <div className="inline-block size-5 rounded border border-border bg-sidebar me-2 align-middle" /> `--sidebar` — Sidebar background
* <div className="inline-block size-5 rounded border border-border bg-sidebar-foreground me-2 align-middle" /> `--sidebar-foreground` — Sidebar text
* <div className="inline-block size-5 rounded border border-border bg-sidebar-primary me-2 align-middle" /> `--sidebar-primary` — Active item background
* <div className="inline-block size-5 rounded border border-border bg-sidebar-accent me-2 align-middle" /> `--sidebar-accent` — Hover and active states
* <div className="inline-block size-5 rounded border border-border bg-sidebar-border me-2 align-middle" /> `--sidebar-border` — Sidebar borders
* <div className="inline-block size-5 rounded border border-border bg-sidebar-ring me-2 align-middle" /> `--sidebar-ring` — Focus rings

Learn more about styling in the [Styling](/docs/styling) section.

## Styling [#styling]

React to collapse mode and peer state with utilities.

```tsx
<Sidebar collapsible="icon">
  <SidebarContent>
    <SidebarGroup className="group-data-[collapsible=icon]:hidden" />
  </SidebarContent>
</Sidebar>
```

```tsx
<SidebarMenuItem>
  <SidebarMenuButton />
  <SidebarMenuAction className="peer-data-[active=true]/menu-button:opacity-100" />
</SidebarMenuItem>
```

## Keyboard shortcut [#keyboard-shortcut]

The toggle listens for &#x2A;*`⌘B`*&#x2A; on macOS and &#x2A;*`Ctrl+B`** elsewhere (`SIDEBAR_KEYBOARD_SHORTCUT` in source). Match that expectation in shortcuts or help copy.

## API Reference [#api-reference]

### SidebarProvider [#sidebarprovider]

`SidebarProvider` must wrap any tree that calls `useSidebar` or renders `Sidebar` / `SidebarTrigger`. It forwards standard `div` props (including `className` and `style`).

| Name           | Type                      | Description                                        |
| -------------- | ------------------------- | -------------------------------------------------- |
| `defaultOpen`  | `boolean`                 | Initial open state on desktop (`true` by default). |
| `open`         | `boolean`                 | Controlled open flag.                              |
| `onOpenChange` | `(open: boolean) => void` | Fires when the open flag changes.                  |

#### Width [#width]

Defaults live beside `SIDEBAR_WIDTH` and `SIDEBAR_WIDTH_MOBILE` inside the registry file. Override per layout with CSS variables on the provider:

```tsx
<SidebarProvider
  style={
    {
      "--sidebar-width": "20rem",
      "--sidebar-width-mobile": "20rem",
    } as React.CSSProperties
  }
>
  <Sidebar />
</SidebarProvider>
```

| Attribute                | Default |
| ------------------------ | ------- |
| `--sidebar-width`        | `16rem` |
| `--sidebar-width-mobile` | `18rem` |
| `--sidebar-width-icon`   | `3rem`  |

### Sidebar [#sidebar]

Primary column component: desktop fixed strip + mobile sheet (via [Sheet](/docs/components/sheet)).

| Property      | Type                                 | Description                                                            |
| ------------- | ------------------------------------ | ---------------------------------------------------------------------- |
| `placement`   | `"left" \| "right"`                  | Which horizontal edge the column hugs (same idea as “side” in shadcn). |
| `variant`     | `"sidebar" \| "floating" \| "inset"` | Visual treatment: flush rail, floating panel, or inset shell.          |
| `collapsible` | `"offcanvas" \| "icon" \| "none"`    | How width collapses.                                                   |

### Collapsible modes [#collapsible-modes]

| Mode        | Behavior                                  |
| ----------- | ----------------------------------------- |
| `offcanvas` | Collapses off-screen; rail can recall it. |
| `icon`      | Shrinks to an icon rail.                  |
| `none`      | Fixed width; no collapse animation.       |

With &#x2A;*`variant="inset"`*&#x2A;, park page content in &#x2A;*`SidebarInset`** so padding, radius, and background line up with the inset shell:

```tsx
<SidebarProvider>
  <Sidebar variant="inset" />
  <SidebarInset>
    <main>{children}</main>
  </SidebarInset>
</SidebarProvider>
```

### useSidebar [#usesidebar]

```tsx
import { useSidebar } from "@/components/ui/sidebar";

export function Example() {
  const {
    state,
    open,
    setOpen,
    openMobile,
    setOpenMobile,
    isMobile,
    toggleSidebar,
  } = useSidebar();
}
```

| Property        | Type                        | Description                               |
| --------------- | --------------------------- | ----------------------------------------- |
| `state`         | `"expanded" \| "collapsed"` | Desktop collapse mode.                    |
| `open`          | `boolean`                   | Desktop drawer expanded.                  |
| `setOpen`       | `(open: boolean) => void`   | Set desktop open.                         |
| `openMobile`    | `boolean`                   | Mobile sheet visibility.                  |
| `setOpenMobile` | `(open: boolean) => void`   | Control the sheet.                        |
| `isMobile`      | `boolean`                   | Breakpoint-derived mobile flag.           |
| `toggleSidebar` | `() => void`                | Toggles desktop or mobile as appropriate. |

### SidebarHeader [#sidebarheader]

Sticky top region—common pattern: workspace switcher or brand row inside a `SidebarMenu`.

```tsx
<Sidebar>
  <SidebarHeader>
    <SidebarMenu>
      <SidebarMenuItem>
        <SidebarMenuButton>
          <span>Select workspace</span>
          <ChevronDown className="ms-auto" />
        </SidebarMenuButton>
      </SidebarMenuItem>
    </SidebarMenu>
  </SidebarHeader>
</Sidebar>
```

Wire menus or [Menu](/docs/components/menu) triggers to `SidebarMenuButton` as needed.

### SidebarFooter [#sidebarfooter]

Sticky bottom slot—profile, settings entry, sign-out, etc.

```tsx
<Sidebar>
  <SidebarFooter>
    <SidebarMenu>
      <SidebarMenuItem>
        <SidebarMenuButton>
          <User2 /> Username
        </SidebarMenuButton>
      </SidebarMenuItem>
    </SidebarMenu>
  </SidebarFooter>
</Sidebar>
```

### SidebarContent [#sidebarcontent]

Wraps scrollable groups. Pass &#x2A;*`scrollFade`** when you want a fade on vertical overflow (see component props in source).

```tsx
<Sidebar>
  <SidebarContent>
    <SidebarGroup />
    <SidebarGroup />
  </SidebarContent>
</Sidebar>
```

| Attribute     | Default |
| ------------- | ------- |
| `--fade-size` | `3rem`  |

### SidebarGroup [#sidebargroup]

A titled block with optional `SidebarGroupAction` and `SidebarGroupContent`.

```tsx
<SidebarGroup>
  <SidebarGroupLabel>Application</SidebarGroupLabel>
  <SidebarGroupAction>
    <Plus /> <span className="sr-only">Add project</span>
  </SidebarGroupAction>
  <SidebarGroupContent />
</SidebarGroup>
```

Collapsible groups pair with [Collapsible](/docs/components/collapsible). `SidebarGroupLabel` is a plain label slot—keep the trigger beside it (or fold the pattern into `SidebarMenu` like the preview at the top of this page):

```tsx
<Collapsible className="group/collapsible" defaultOpen>
  <SidebarGroup>
    <div className="flex items-center gap-2 px-2">
      <SidebarGroupLabel className="flex-1 px-0">Help</SidebarGroupLabel>
      <CollapsibleTrigger
        className="rounded-md p-1.5 outline-none ring-sidebar-ring focus-visible:ring-2"
        type="button"
      >
        <ChevronDown className="size-4 transition-transform group-data-[state=open]/collapsible:rotate-180" />
      </CollapsibleTrigger>
    </div>
    <CollapsibleContent>
      <SidebarGroupContent />
    </CollapsibleContent>
  </SidebarGroup>
</Collapsible>
```

### SidebarMenu [#sidebarmenu]

Row list inside a group—map data to `SidebarMenuItem` / `SidebarMenuButton`.

```tsx
<SidebarMenu>
  {projects.map((project) => (
    <SidebarMenuItem key={project.name}>
      <SidebarMenuButton asChild>
        <a href={project.url}>
          <project.icon />
          <span>{project.name}</span>
        </a>
      </SidebarMenuButton>
    </SidebarMenuItem>
  ))}
</SidebarMenu>
```

### SidebarMenuButton [#sidebarmenubutton]

Default renders a **Button*&#x2A;; use &#x2A;*`asChild`*&#x2A; for links. &#x2A;*`isActive`*&#x2A; highlights the active route; &#x2A;*`tooltip`** surfaces collapsed labels.

```tsx
<SidebarMenuButton asChild isActive>
  <a href="#">Home</a>
</SidebarMenuButton>
```

### SidebarMenuAction [#sidebarmenuaction]

Icon-only or compact action aligned to a row. Use &#x2A;*`showOnHover`** to reveal on row hover.

```tsx
<SidebarMenuItem>
  <SidebarMenuButton asChild>
    <a href="#">
      <Home />
      <span>Home</span>
    </a>
  </SidebarMenuButton>
  <SidebarMenuAction>
    <Plus /> <span className="sr-only">Add project</span>
  </SidebarMenuAction>
</SidebarMenuItem>
```

### SidebarMenuSub [#sidebarmenusub]

Nested list hanging off a parent item.

```tsx
<SidebarMenuItem>
  <SidebarMenuButton />
  <SidebarMenuSub>
    <SidebarMenuSubItem>
      <SidebarMenuSubButton href="#">Child</SidebarMenuSubButton>
    </SidebarMenuSubItem>
  </SidebarMenuSub>
</SidebarMenuItem>
```

### SidebarMenuBadge [#sidebarmenubadge]

Small count or pill beside a row.

```tsx
<SidebarMenuItem>
  <SidebarMenuButton />
  <SidebarMenuBadge>24</SidebarMenuBadge>
</SidebarMenuItem>
```

### SidebarMenuSkeleton [#sidebarmenuskeleton]

Placeholder rows while async routes or prefs load.

```tsx
<SidebarMenu>
  {Array.from({ length: 5 }).map((_, index) => (
    <SidebarMenuItem key={index}>
      <SidebarMenuSkeleton />
    </SidebarMenuItem>
  ))}
</SidebarMenu>
```

### SidebarTrigger [#sidebartrigger]

Prebuilt toggle wired to context—drop next to your page title or in a toolbar.

```tsx
import { useSidebar } from "@/components/ui/sidebar";

export function CustomTrigger() {
  const { toggleSidebar } = useSidebar();
  return <button type="button" onClick={toggleSidebar}>Toggle</button>;
}
```

Prefer `SidebarTrigger` when you want the default styling and accessibility bundle.

### SidebarRail [#sidebarrail]

Draggable edge control that expands or collapses the desktop rail—place after header/content/footer inside `Sidebar`.

```tsx
<Sidebar>
  <SidebarHeader />
  <SidebarContent>
    <SidebarGroup />
  </SidebarContent>
  <SidebarFooter />
  <SidebarRail />
</Sidebar>
```


# Signature Pad (/docs/components/signature-pad)



<ComponentPreview componentName="signature-pad" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/signature-pad
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/signature-pad.tsx" src="/signature-pad.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { SignaturePad } from "@/components/ui/signature-pad";
```

```tsx
<SignaturePad />
```

## Examples [#examples]

### Image preview [#image-preview]

Use the `onDrawEnd` callback to capture the signature as an image.

The callback receives the `getDataUrl(type)` method that returns a promise that resolves to a data URL.

<ComponentPreview componentName="signature-pad" fileName="example-image-preview" />

### With field [#with-field]

Wrap the signature pad in a `Field` with `FieldLabel` and `FieldHelper` for accessible form integration.

<ComponentPreview componentName="signature-pad" fileName="example-field" />

## API Reference [#api-reference]

### SignaturePad [#signaturepad]

Root component. Canvas for drawing signatures. Manages strokes and export.

| Prop        | Type                                | Default |
| ----------- | ----------------------------------- | ------- |
| `disabled`  | `boolean`                           | `false` |
| `required`  | `boolean`                           | `false` |
| `readOnly`  | `boolean`                           | `false` |
| `name`      | `string`                            | -       |
| `onDraw`    | `(details: DrawDetails) => void`    | -       |
| `onDrawEnd` | `(details: DrawEndDetails) => void` | -       |
| `className` | `string`                            | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/signature-pad#api-reference).


# Skeleton (/docs/components/skeleton)



<ComponentPreview componentName="skeleton" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/skeleton
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/skeleton.tsx" src="/skeleton.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { 
  Skeleton,
  SkeletonCircle,
  SkeletonText,
} from "@/components/ui/skeleton";
```

```tsx
<SkeletonCircle />
<SkeletonText />
<Skeleton />
```

## Examples [#examples]

### Skeleton [#skeleton]

Rectangular skeleton placeholder.

<ComponentPreview componentName="skeleton" fileName="example-skeleton" />

### Circle [#circle]

Circular skeleton placeholder.

<ComponentPreview componentName="skeleton" fileName="example-skeleton-circle" />

### Text [#text]

Use the `lines` prop to control the number of placeholder lines; the last line is shorter by default.

<ComponentPreview componentName="skeleton" fileName="example-skeleton-text" />

### Loading cards [#loading-cards]

<ComponentPreview componentName="skeleton" fileName="example-loading-card" />

## API Reference [#api-reference]

### Skeleton [#skeleton-1]

Rectangular loading placeholder.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### SkeletonCircle [#skeletoncircle]

Circular loading placeholder.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### SkeletonText [#skeletontext]

Multi-line text placeholder. Last line is shorter by default to mimic text.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `lines`     | `number`  | `2`     |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/skeleton#api-reference).


# Skip Nav (/docs/components/skip-nav)



<ComponentPreview componentName="skip-nav" />

> Click on the "Preview" tab and use the tab key to see the skip to content link.

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/skip-nav
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/skip-nav.tsx" src="/skip-nav.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

* Place `SkipNavLink` as one of the first focusable elements on the page.
* Use `SkipNavContent` to wrap your main content. It renders a div with an id that the link targets.

```tsx
import { SkipNavContent, SkipNavLink } from "@/components/ui/skip-nav";
```

```tsx
<SkipNavLink />
<nav>...</nav>
<SkipNavContent />
<main>Your main content</main>
```

## API Reference [#api-reference]

### SkipNavLink [#skipnavlink]

| Prop        | Type      | Default              |
| ----------- | --------- | -------------------- |
| `id`        | `string`  | `"skip-nav-content"` |
| `className` | `string`  | -                    |
| `asChild`   | `boolean` | `false`              |

### SkipNavContent [#skipnavcontent]

| Prop        | Type      | Default              |
| ----------- | --------- | -------------------- |
| `id`        | `string`  | `"skip-nav-content"` |
| `className` | `string`  | -                    |
| `asChild`   | `boolean` | `false`              |


# Slider (/docs/components/slider)



<ComponentPreview componentName="slider" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/slider
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Field](/docs/components/field)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/slider.tsx" src="/slider.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

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

```tsx
<Slider />
```

## Controlled [#controlled]

Control the value with `value` and `onValueChange` for a controlled slider.

<ComponentPreview componentName="slider" fileName="example-controlled" />

## Examples [#examples]

### With label and value [#with-label-and-value]

Use `<Field>`, `<SliderLabel>`, and `<SliderValue>` for accessible labelling and to show the current value.

<ComponentPreview componentName="slider" fileName="example-with-label" />

### Range [#range]

Use an array with two values for a range slider.

<ComponentPreview componentName="slider" fileName="example-range" />

### Vertical [#vertical]

Use `orientation="vertical"` for a vertical slider.

<ComponentPreview componentName="slider" fileName="example-vertical" />

### Disabled [#disabled]

Use the `disabled` prop to disable the slider.

<ComponentPreview componentName="slider" fileName="example-disabled" />

### Min and max [#min-and-max]

Set `min` and `max` to constrain the slider's value range.

<ComponentPreview componentName="slider" fileName="example-min-max" />

### Marks [#marks]

The `showMarkers` and `markerInterval` props display markers and control the interval between them.

<ComponentPreview componentName="slider" fileName="example-marks" />

### Step [#step]

Set `step` to control the slider's granularity.

Use with `showMarkers` and `markerLabels` to show custom labels on the markers.

<ComponentPreview componentName="slider" fileName="example-step" />

<Alert>
  <InfoIcon />

  <AlertDescription>
    Marks are only supported for `horizontal` sliders.
  </AlertDescription>
</Alert>

## API Reference [#api-reference]

### Slider [#slider]

Root component. Manages value, track, range, and thumb(s).

| Prop             | Type                                    | Default        |
| ---------------- | --------------------------------------- | -------------- |
| `value`          | `number[]`                              | -              |
| `defaultValue`   | `number[]`                              | -              |
| `onValueChange`  | `(details: ValueChangeDetails) => void` | -              |
| `min`            | `number`                                | `0`            |
| `max`            | `number`                                | `100`          |
| `step`           | `number`                                | `1`            |
| `orientation`    | `"horizontal" \| "vertical"`            | `"horizontal"` |
| `disabled`       | `boolean`                               | `false`        |
| `showMarkers`    | `boolean`                               | `false`        |
| `markerInterval` | `number`                                | `1`            |
| `markerLabels`   | `string[]`                              | `[]`           |
| `className`      | `string`                                | -              |

### SliderLabel [#sliderlabel]

Label for the slider. Required for accessibility.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### SliderValue [#slidervalue]

Shows the current value. Useful for numeric display or formatting.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/slider#api-reference).


# Spinner (/docs/components/spinner)



<ComponentPreview componentName="spinner" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/spinner
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/spinner.tsx" src="/spinner.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Spinner } from "@/components/ui/spinner";
```

```tsx
<Spinner />
```

## Customization [#customization]

## Examples [#examples]

### Size [#size]

Use the `size-*` utility class to change the size of the spinner.

<ComponentPreview componentName="spinner" fileName="example-size" />

### Badge [#badge]

Add a spinner to a badge to indicate a loading state.

<ComponentPreview componentName="spinner" fileName="example-badge" />

### Input Group [#input-group]

Use a spinner in an input group addon to indicate a loading or validating state.

<ComponentPreview componentName="spinner" fileName="example-input-group" />

## API Reference [#api-reference]

### Spinner [#spinner]

Use the `Spinner` component to display a loading indicator. It forwards SVG props and supports `className` for sizing and styling.

| Prop         | Type     | Default     |
| ------------ | -------- | ----------- |
| `className`  | `string` | -           |
| `aria-label` | `string` | `"Loading"` |


# Status (/docs/components/status)



<ComponentPreview componentName="status" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/status
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Import the following variables into your CSS file
      </Step>

      <CodeCollapsibleWrapper>
        ```css
        @theme inline {
          --color-destructive-foreground: var(--destructive-foreground);
          --color-info: var(--info);
          --color-info-foreground: var(--info-foreground);
          --color-success: var(--success);
          --color-success-foreground: var(--success-foreground);
          --color-warning: var(--warning);
          --color-warning-foreground: var(--warning-foreground);
        }

        :root {
          --destructive-foreground: var(--color-red-700);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-700);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-700);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-700);
        }

        .dark {
          --destructive-foreground: var(--color-red-400);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-400);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-400);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-400);
        }
        ```
      </CodeCollapsibleWrapper>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/status.tsx" src="/status.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Status } from "@/components/ui/status";
```

```tsx
<Status variant="success" />
```

## Variants [#variants]

### Default [#default]

<ComponentPreview componentName="status" fileName="example-variant-default" />

### Info [#info]

<ComponentPreview componentName="status" fileName="example-variant-info" />

### Success [#success]

<ComponentPreview componentName="status" fileName="example-variant-success" />

### Warning [#warning]

<ComponentPreview componentName="status" fileName="example-variant-warning" />

### Destructive [#destructive]

<ComponentPreview componentName="status" fileName="example-variant-destructive" />

## Sizes [#sizes]

### Small [#small]

<ComponentPreview componentName="status" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="status" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="status" fileName="example-size-lg" />

## With Badge [#with-badge]

<ComponentPreview componentName="status" fileName="example-with-badge" />

## With Icon [#with-icon]

Place an icon inside the `Status`.

<ComponentPreview componentName="status" fileName="example-with-icon" />

## Custom Size [#custom-size]

Use `size-*` on `Status` to customize the size.

<ComponentPreview componentName="status" fileName="example-custom-size" />

## Custom Color [#custom-color]

Use `bg-*` and `text-*` utility classes to customize the color.

<ComponentPreview componentName="status" fileName="example-custom-color" />

## API Reference [#api-reference]

### Status [#status]

Status badge or indicator.

| Prop        | Type                                                | Default     |
| ----------- | --------------------------------------------------- | ----------- |
| `variant`   | `"success" \| "info" \| "warning" \| "destructive"` | `"success"` |
| `size`      | `"sm" \| "md" \| "lg"`                              | `"md"`      |
| `className` | `string`                                            | -           |
| `asChild`   | `boolean`                                           | `false`     |


# Steps (/docs/components/steps)



<ComponentPreview componentName="steps" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/steps
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/steps.tsx" src="/steps.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Steps
├── StepsList
│   └── StepsItem
│       ├── StepsTrigger
│       ├── StepsIndicator
│       ├── StepsSeparator
│       ├── StepsTitle
│       └── StepsDescription
├── StepsContent
├── StepsCompletedContent
├── StepsPrevious
└── StepsNext
```

## Usage [#usage]

```tsx
import {
  Steps,
  StepsList,
  StepsItem,
  StepsTrigger,
  StepsSeparator,
  StepsIndicator,
  StepsTitle,
  StepsDescription,
  StepsContent,
  StepsCompletedContent,
  StepsNext,
  StepsPrevious
} from "@/components/ui/steps";
```

```tsx
<Steps>
  <StepsList>
    <StepsItem>
      <StepsTrigger>
        <StepsIndicator />
        <StepsTitle />
      </StepsTrigger>
      <StepsSeparator />
    </StepsItem>
  </StepsList>
  <StepsContent />
  <StepsCompletedContent />
  <StepsPrevious />
  <StepsNext />
</Steps>
```

## Examples [#examples]

### Title [#title]

Use `StepsTitle` to display a description for each step.

<ComponentPreview componentName="steps" fileName="example-title" />

### Description [#description]

Use `StepsDescription` to display a description for each step.

<ComponentPreview componentName="steps" fileName="example-description" />

### Vertical [#vertical]

Use `orientation="vertical"` for a vertical layout.

<ComponentPreview componentName="steps" fileName="example-vertical" />

### Loading [#loading]

<ComponentPreview componentName="steps" fileName="example-loading" />

### Controlled [#controlled]

Use the `step` and `onStepChange` props to control the active step programmatically.

<ComponentPreview componentName="steps" fileName="example-controlled" />

### Custom Icon [#custom-icon]

<ComponentPreview componentName="steps" fileName="example-icon" />

## API Reference [#api-reference]

### Steps [#steps]

Root component. Manages step state and connectors.

| Prop             | Type                                   | Default        |
| ---------------- | -------------------------------------- | -------------- |
| `count`          | `number`                               | `-`            |
| `step`           | `number`                               | `-`            |
| `defaultStep`    | `number`                               | `-`            |
| `orientation`    | `"horizontal" \| "vertical"`           | `"horizontal"` |
| `linear`         | `boolean`                              | `false`        |
| `onStepChange`   | `(details: StepChangeDetails) => void` | `-`            |
| `onStepComplete` | `() => void`                           | `-`            |

### StepsList [#stepslist]

Wraps the list of steps. Handles connector layout.

| Attribute           | Default        |
| ------------------- | -------------- |
| `--steps-gutter`    | `--spacing(2)` |
| `--steps-icon-size` | `--spacing(4)` |
| `--steps-size`      | `--spacing(8)` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/steps#api-reference).


# Switch (/docs/components/switch)



<ComponentPreview componentName="switch" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/switch
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/switch.tsx" src="/switch.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

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

```tsx
<Switch />
```

## Controlled [#controlled]

Use the `checked` and `onCheckedChange` props to control the switch state programmatically.

<ComponentPreview componentName="switch" fileName="example-controlled" />

## States [#states]

### Invalid [#invalid]

Use the `invalid` prop on the `Field` or in the `Switch` component to mark the switch as invalid.

<ComponentPreview componentName="switch" fileName="example-invalid" />

## Examples [#examples]

### Disabled [#disabled]

Use the `disabled` prop to disable the switch.

<ComponentPreview componentName="switch" fileName="example-disabled" />

### With Description [#with-description]

Use `FieldDescription` to add a description to the switch.

<ComponentPreview componentName="switch" fileName="example-description" />

### Card Style [#card-style]

Use a card-style layout with the switch for a more prominent display.

<ComponentPreview componentName="switch" fileName="example-card" />

### Form Integration [#form-integration]

Integrate the switch into a form with proper validation and error handling.

<ComponentPreview componentName="switch" fileName="example-form" />

### Customizing Size [#customizing-size]

The switch size is controlled by the `[--size-*]` CSS variable.

<ComponentPreview componentName="switch" fileName="example-size" />

## API Reference [#api-reference]

### Switch [#switch]

Toggle switch for on/off state. Use with a form control.

| Prop              | Type                                      | Default |
| ----------------- | ----------------------------------------- | ------- |
| `checked`         | `boolean`                                 | `-`     |
| `defaultChecked`  | `boolean`                                 | `false` |
| `disabled`        | `boolean`                                 | `false` |
| `invalid`         | `boolean`                                 | `false` |
| `name`            | `string`                                  | `-`     |
| `value`           | `string \| number`                        | `"on"`  |
| `onCheckedChange` | `(details: CheckedChangeDetails) => void` | `-`     |
| `className`       | `string`                                  | `-`     |

| Attribute | Default        |
| --------- | -------------- |
| `--size`  | `--spacing(4)` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/switch#api-reference).


# Table (/docs/components/table)



<ComponentPreview componentName="table" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/table
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/table.tsx" src="/table.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Table
├── TableCaption
├── TableHeader
│   └── TableRow
│       └── TableHead
├── TableBody
│   └── TableRow
│       └── TableCell
└── TableFooter
    └── TableRow
        └── TableCell
```

## Usage [#usage]

```tsx
import { 
  Table, 
  TableBody, 
  TableCaption, 
  TableCell, 
  TableHead, 
  TableHeader, 
  TableRow,
  TableFooter,
} from "@/components/ui/table";
```

```tsx
<Table>
  <TableCaption />
  <TableHeader>
    <TableRow>
      <TableHead />
      <TableHead />
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell />
      <TableCell />
    </TableRow>
  </TableBody>
  <TableFooter />
</Table>
```

## Accessibility [#accessibility]

Always use a `TableCaption` to help assistive technologies announce what the table represents.

Use with the `sr-only` class to make the caption screen-reader only if you don't want to show it.

```tsx showLineNumbers
<Table>
  <TableCaption className="sr-only">
    Monthly revenue by product.
  </TableCaption>
  {/* ... */}
</Table>
```

## Examples [#examples]

### Striped [#striped]

Use `variant="striped"` on `Table` for alternating row backgrounds.

<ComponentPreview componentName="table" fileName="example-striped" />

### With footer [#with-footer]

Use `TableFooter` for summary rows, totals, or notes.

<ComponentPreview componentName="table" fileName="example-footer" />

### With actions [#with-actions]

Add an actions column with buttons per row.

<ComponentPreview componentName="table" fileName="example-actions" />

### With action bar [#with-action-bar]

Use checkboxes for row selection and an action bar that appears when one or more rows are selected. See the [action bar](/docs/components/action-bar) component.

<ComponentPreview componentName="table" fileName="example-action-bar" />

### With context menu [#with-context-menu]

Wrap each row with `ContextMenuTrigger` so right-clicking shows a context menu with row actions.

<ComponentPreview componentName="table" fileName="example-context-menu" />

### Disable row hover [#disable-row-hover]

Set `isHoverable={false}` on `Table` to disable the hover background on body rows.

<ComponentPreview componentName="table" fileName="example-not-hoverable" />

## API Reference [#api-reference]

### Table [#table]

Scrollable wrapper around a native table. Supports striped and hover variants.

| Prop          | Type                   | Default   |
| ------------- | ---------------------- | --------- |
| `variant`     | `"plain" \| "striped"` | `"plain"` |
| `isHoverable` | `boolean`              | `true`    |
| `className`   | `string`               | `-`       |
| `asChild`     | `boolean`              | `false`   |

### TableHeader [#tableheader]

Table header row group.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TableBody [#tablebody]

Table body row group.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TableFooter [#tablefooter]

Table footer row group for totals or summary rows.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TableRow [#tablerow]

A single table row.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TableHead [#tablehead]

Header cell for column titles.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TableCell [#tablecell]

Data cell for body or footer rows.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TableCaption [#tablecaption]

Accessible caption describing the table. Use `sr-only` for screen-reader only.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |


# Tabs (/docs/components/tabs)



<ComponentPreview componentName="tabs" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/tabs
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/tabs.tsx" src="/tabs.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Tabs
├── TabsList
│   └── TabsTrigger
└── TabsContent
```

## Usage [#usage]

```tsx
import { 
  Tabs,
  TabsList,
  TabsTrigger,
  TabsContent
} from "@/components/ui/tabs";
```

```tsx
<Tabs>
  <TabsList>
    <TabsTrigger value="1">Tab 1</TabsTrigger>
    <TabsTrigger value="2">Tab 2</TabsTrigger>
  </TabsList>
  <TabsContent value="1">Tab 1 content</TabsContent>
  <TabsContent value="2">Tab 2 content</TabsContent>
</Tabs>
```

## Controlled [#controlled]

Use `value` and `onValueChange` to control the active tab programmatically.

<ComponentPreview componentName="tabs" fileName="example-controlled" />

## Variant [#variant]

### Default [#default]

<ComponentPreview componentName="tabs" fileName="example-variant-default" />

### Underline [#underline]

<ComponentPreview componentName="tabs" fileName="example-variant-underline" />

## Orientation [#orientation]

Use the `orientation` prop on `Tabs` to lay out tabs horizontally or vertically.

### Horizontal [#horizontal]

<ComponentPreview componentName="tabs" fileName="example-orientation-horizontal" />

### Vertical [#vertical]

<ComponentPreview componentName="tabs" fileName="example-orientation-vertical" />

## States [#states]

### Disabled [#disabled]

Disable individual tabs with the `disabled` prop on `TabsTrigger`. Disabled tabs are not focusable or selectable.

<ComponentPreview componentName="tabs" fileName="example-disabled" />

## Examples [#examples]

### Vertical with underline [#vertical-with-underline]

Combine `orientation="vertical"` on `Tabs` with `variant="underline"` on `TabsList`.

<ComponentPreview componentName="tabs" fileName="example-variant-underline-orientation-vertical" />

### With icons [#with-icons]

<ComponentPreview componentName="tabs" fileName="example-with-icons" />

## API Reference [#api-reference]

### Tabs [#tabs]

Root element. Manages tab state and layout.

| Prop            | Type                                    | Default        |
| --------------- | --------------------------------------- | -------------- |
| `value`         | `string`                                | `-`            |
| `defaultValue`  | `string`                                | `-`            |
| `onValueChange` | `(details: ValueChangeDetails) => void` | `-`            |
| `orientation`   | `"horizontal" \| "vertical"`            | `"horizontal"` |
| `className`     | `string`                                | `-`            |

### TabsList [#tabslist]

Container for tab triggers and the selection indicator.

| Prop        | Type                       | Default     |
| ----------- | -------------------------- | ----------- |
| `variant`   | `"default" \| "underline"` | `"default"` |
| `className` | `string`                   | `-`         |

### TabsTrigger [#tabstrigger]

Button that selects a tab. Must have a `value` matching a `TabsContent` panel.

| Prop        | Type      | Default      |
| ----------- | --------- | ------------ |
| `value`     | `string`  | **required** |
| `disabled`  | `boolean` | `false`      |
| `className` | `string`  | `-`          |

### TabsContent [#tabscontent]

Panel shown when its tab is selected. Must have a `value` matching a `TabsTrigger`.

| Prop        | Type     | Default      |
| ----------- | -------- | ------------ |
| `value`     | `string` | **required** |
| `className` | `string` | `-`          |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/tabs#api-reference).


# Tags Input (/docs/components/tags-input)



<ComponentPreview componentName="tags-input" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/tags-input
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Input Group](/docs/components/input-group)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/tags-input.tsx" src="/tags-input.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
TagsInput
└── TagsInputContext
    └── TagsInputItem
```

## Usage [#usage]

```tsx
import {
  TagsInput,
  TagsInputContext,
  TagsInputItem,
} from "@/components/ui/tags-input";
```

```tsx
<TagsInput defaultValue={["React", "Solid"]}>
  <TagsInputContext>
      {({ value }) =>
        value.map((value, index) => (
          <TagsInputItem index={index} key={value} value={value}>
            {value}
          </TagsInputItem>
        ))
      }
    </TagsInputContext>
</TagsInput>
```

## Controlled [#controlled]

Use `value` and `onValueChange` to control the tags array.

<ComponentPreview componentName="tags-input" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

Use the `disabled` prop to disable the tags input. Users cannot add, remove, or edit tags.

<ComponentPreview componentName="tags-input" fileName="example-disabled" />

### Invalid [#invalid]

Use the `invalid` prop to mark the tags input as invalid for form validation.

<ComponentPreview componentName="tags-input" fileName="example-invalid" />

## Sizes [#sizes]

Use the `size` prop on `TagsInput` to change the control and input height.

### Small [#small]

<ComponentPreview componentName="tags-input" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="tags-input" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="tags-input" fileName="example-size-lg" />

## Examples [#examples]

### Blur Behavior [#blur-behavior]

Use `blurBehavior="add"` to add the current input value as a tag when the field loses focus.

<ComponentPreview componentName="tags-input" fileName="example-blur-behavior" />

### Controlled Input Value [#controlled-input-value]

Use `inputValue` and `onInputValueChange` to control the text field independently.

<ComponentPreview componentName="tags-input" fileName="example-controlled-input-value" />

### Delimiter [#delimiter]

Use `delimiter` with a regex to split tags when typing or pasting separators.

<ComponentPreview componentName="tags-input" fileName="example-custom-delimiter" />

### Disabled Editing [#disabled-editing]

Pass `editable={false}` to prevent editing existing tags after creation.

<ComponentPreview componentName="tags-input" fileName="example-disable-editing" />

### Max Tag Length [#max-tag-length]

Use `maxLength` to cap characters per tag.

<ComponentPreview componentName="tags-input" fileName="example-max-length" />

### Max With Overflow [#max-with-overflow]

Use `max` with `allowOverflow` to allow exceeding the limit while marking the root as invalid.

<ComponentPreview componentName="tags-input" fileName="example-max-with-overflow" />

### Paste Behavior [#paste-behavior]

Use `addOnPaste` with `delimiter` to create multiple tags from pasted text.

<ComponentPreview componentName="tags-input" fileName="example-paste-behavior" />

### Sanitize [#sanitize]

Use `sanitizeValue` to normalize tag text before tags are added.

<ComponentPreview componentName="tags-input" fileName="example-sanitize-value" />

### Validation [#validation]

Use `validate` to accept or reject tags before they are added.

<ComponentPreview componentName="tags-input" fileName="example-validation" />

### With Combobox [#with-combobox]

<ComponentPreview componentName="tags-input" fileName="example-combobox" />

### With Field [#with-field]

Wrap with [Field](/docs/components/field) for labels, descriptions, and validation messaging.

<ComponentPreview componentName="tags-input" fileName="example-field" />

## API Reference [#api-reference]

### TagsInput [#tagsinput]

Root component. Composes the control, input, and hidden field for form submission.

| Prop                 | Type                        | Default                   |
| -------------------- | --------------------------- | ------------------------- |
| `size`               | `"sm" \| "md" \| "lg"`      | `"md"`                    |
| `showClear`          | `boolean`                   | `true`                    |
| `defaultValue`       | `string[]`                  | -                         |
| `value`              | `string[]`                  | -                         |
| `inputValue`         | `string`                    | -                         |
| `defaultInputValue`  | `string`                    | -                         |
| `max`                | `number`                    | `Infinity`                |
| `maxLength`          | `number`                    | -                         |
| `delimiter`          | `string \| RegExp`          | `","`                     |
| `allowDuplicates`    | `boolean`                   | `false`                   |
| `allowOverflow`      | `boolean`                   | -                         |
| `disabled`           | `boolean`                   | -                         |
| `invalid`            | `boolean`                   | -                         |
| `required`           | `boolean`                   | -                         |
| `editable`           | `boolean`                   | `false`                   |
| `addOnPaste`         | `boolean`                   | `false`                   |
| `blurBehavior`       | `"add" \| "clear"`          | -                         |
| `validate`           | `(details) => boolean`      | -                         |
| `sanitizeValue`      | `(value: string) => string` | `(value) => value.trim()` |
| `onValueChange`      | `(details) => void`         | -                         |
| `onInputValueChange` | `(details) => void`         | -                         |
| `onHighlightChange`  | `(details) => void`         | -                         |
| `onValueInvalid`     | `(details) => void`         | -                         |
| `className`          | `string`                    | -                         |

### TagsInputInput [#tagsinputinput]

Borderless text field for adding new tags. Rendered inside `TagsInput` by default.

| Prop          | Type     | Default |
| ------------- | -------- | ------- |
| `placeholder` | `string` | -       |
| `className`   | `string` | -       |

### TagsInputItem [#tagsinputitem]

Represents a single tag. Requires `index` and `value`. Pass the label as children. Renders the delete trigger and edit input. Chip height follows the root `size` (`sm`, `md`, `lg`). Supports `data-highlighted` when navigated by keyboard.

| Prop         | Type      | Default      |
| ------------ | --------- | ------------ |
| `index`      | `number`  | **required** |
| `value`      | `string`  | **required** |
| `showDelete` | `boolean` | `true`       |
| `disabled`   | `boolean` | -            |
| `className`  | `string`  | -            |

### TagsInputClearTrigger [#tagsinputcleartrigger]

Clears all tags.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

***

For the full list of props and context methods, see the [Ark UI documentation](https://ark-ui.com/docs/components/tags-input#api-reference).


# Textarea (/docs/components/textarea)



<ComponentPreview componentName="textarea" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/textarea
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/textarea.tsx" src="/textarea.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Textarea } from "@/components/ui/textarea";
```

```tsx
<Textarea />
```

## Controlled [#controlled]

Control the value with `value` and `onChange`.

<ComponentPreview componentName="textarea" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

Disable the textarea with the `disabled` prop. Use `Field` with `disabled` to disable the whole field (label + textarea).

<ComponentPreview componentName="textarea" fileName="example-disabled" />

### Invalid [#invalid]

Use the `invalid` prop on `Field` or `Textarea` to show invalid state.

<ComponentPreview componentName="textarea" fileName="example-invalid" />

## Examples [#examples]

### Autoresize [#autoresize]

Use `autoresize` to make the textarea grow with content.

<ComponentPreview componentName="textarea" fileName="example-autoresize" />

### With Field [#with-field]

Wrap the textarea in a `Field` and add `FieldLabel` and `FieldDescription`.

<ComponentPreview componentName="textarea" fileName="example-with-field" />

### With Input Group [#with-input-group]

Use `FieldGroup` to group multiple `Field` blocks. Combine textarea with other inputs and action buttons.

<ComponentPreview componentName="input-group" fileName="example-input-group" />

### Form Integration [#form-integration]

<ComponentPreview componentName="textarea" fileName="example-form" />

## API Reference [#api-reference]

### Textarea [#textarea]

Multi-line text input. Accepts all native textarea attributes.

| Prop         | Type      | Default |
| ------------ | --------- | ------- |
| `autoresize` | `boolean` | `true`  |
| `className`  | `string`  | `-`     |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/field#api-reference).


# Timer (/docs/components/timer)



<ComponentPreview componentName="timer" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/timer
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/timer.tsx" src="/timer.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Timer
├── TimerArea
│   ├── TimerItemGroup
│   │   ├── TimerItem
│   │   └── TimerItemLabel
│   ├── TimerSeparator
└── TimerControl
    ├── TimerActionTrigger
    ├── TimerStart
    ├── TimerPause
    ├── TimerResume
    ├── TimerReset
    ├── TimerRestart
    └── TimerPlay
```

## Usage [#usage]

```tsx
import {
  Timer,
  TimerArea,
  TimerItem,
  TimerItemGroup,
  TimerItemLabel,
  TimerSeparator,
  TimerControl,
  TimerActionTrigger,
  TimerStart,
  TimerPause,
  TimerResume,
  TimerReset,
  TimerRestart,
  TimerPlay,
} from "@/components/ui/timer";
```

```tsx
<Timer targetMs={3600000} startMs={2400000}>
  <TimerArea>
    <TimerItemGroup>
      <TimerItem type="hours" />
      <TimerItemLabel>Hours</TimerItemLabel>
    </TimerItemGroup>
    <TimerSeparator />
    <TimerItemGroup>
      <TimerItem type="minutes" />
      <TimerItemLabel>Minutes</TimerItemLabel>
    </TimerItemGroup>
    <TimerSeparator />
    <TimerItemGroup>
      <TimerItem type="seconds" />
      <TimerItemLabel>Seconds</TimerItemLabel>
    </TimerItemGroup>
  </TimerArea>
  <TimerControl>
    <TimerPlay>Go</TimerPlay>
    <TimerPause>Pause</TimerPause>
    <TimerReset>Reset</TimerReset>
  </TimerControl>
</Timer>
```

## Controlled [#controlled]

Handle `onTick` and `onComplete` to react to timer progress and completion.

<ComponentPreview componentName="timer" fileName="example-controlled" />

## Orientation [#orientation]

Use the `orientation` prop on `TimerItemGroup` to change the orientation of the timer.

### Vertical [#vertical]

<ComponentPreview componentName="timer" fileName="example-orientation-vertical" />

### Horizontal [#horizontal]

<ComponentPreview componentName="timer" fileName="example-orientation-horizontal" />

## Examples [#examples]

### Countdown [#countdown]

Create a countdown by setting `countdown` to `true` and `startMs` to the initial duration.

<ComponentPreview componentName="timer" fileName="example-countdown" />

### Date-based [#date-based]

Use `remainingMsUntilDate` to derive `startMs` from a calendar date.

<ComponentPreview componentName="timer" fileName="example-countdown-date" />

### Interval [#interval]

Use the `interval` prop to control update frequency.

<ComponentPreview componentName="timer" fileName="example-interval" />

### Pomodoro [#pomodoro]

Alternate between work and break sessions using `onComplete`.

<ComponentPreview componentName="timer" fileName="example-pomodoro" />

<Alert>
  <InfoIcon />

  <AlertTitle>
    Trigger Behavior
  </AlertTitle>

  <AlertDescription>
    Triggers hide when their action is not available. To keep a control in the layout, pass `hidden={false}`.
  </AlertDescription>
</Alert>

### Custom separator [#custom-separator]

Pass children to `TimerSeparator` to override the default colon (`:`).

<ComponentPreview componentName="timer" fileName="example-custom-separator" />

## API Reference [#api-reference]

### Timer [#timer]

Root component. Runs a stopwatch or countdown and provides timer state to child parts.

| Prop         | Type                             | Default |
| ------------ | -------------------------------- | ------- |
| `targetMs`   | `number`                         | `0`     |
| `startMs`    | `number`                         | `0`     |
| `countdown`  | `boolean`                        | `false` |
| `interval`   | `number`                         | `1000`  |
| `autoStart`  | `boolean`                        | `false` |
| `onTick`     | `(details: TickDetails) => void` | `-`     |
| `onComplete` | `() => void`                     | `-`     |

### TimerArea [#timerarea]

Live region that exposes the formatted time to assistive tech and lays out digit groups.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TimerItemGroup [#timeritemgroup]

Groups a `TimerItem` with its `TimerItemLabel` and sets stack direction via `orientation`.

| Prop          | Type                         | Default      |
| ------------- | ---------------------------- | ------------ |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` |
| `className`   | `string`                     | `-`          |
| `asChild`     | `boolean`                    | `false`      |

### TimerItemLabel [#timeritemlabel]

Caption for the adjacent `TimerItem` (for example, “minutes”).

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TimerItem [#timeritem]

Renders one time field from the current timer value.

| Prop      | Type                                                            | Default     |
| --------- | --------------------------------------------------------------- | ----------- |
| `type`    | `"days" \| "hours" \| "minutes" \| "seconds" \| "milliseconds"` | `"seconds"` |
| `asChild` | `boolean`                                                       | `false`     |

### TimerSeparator [#timerseparator]

Visual delimiter between item groups (defaults to `:` when children are omitted).

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TimerControl [#timercontrol]

Toolbar row for timer action controls.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TimerActionTrigger [#timeractiontrigger]

Button that dispatches a timer action.

| Prop      | Type                                                     | Default   |
| --------- | -------------------------------------------------------- | --------- |
| `action`  | `"start" \| "pause" \| "resume" \| "reset" \| "restart"` | `"start"` |
| `hidden`  | `boolean`                                                | `-`       |
| `asChild` | `boolean`                                                | `false`   |

### TimerStart [#timerstart]

Starts the timer. Wraps `TimerActionTrigger` with `action="start"`.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `hidden`    | `boolean` | `-`     |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TimerPause [#timerpause]

Pauses a running timer. Wraps `TimerActionTrigger` with `action="pause"`.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `hidden`    | `boolean` | `-`     |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TimerResume [#timerresume]

Resumes from paused. Wraps `TimerActionTrigger` with `action="resume"`.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `hidden`    | `boolean` | `-`     |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TimerReset [#timerreset]

Resets the timer to its initial `startMs` / idle state.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `hidden`    | `boolean` | `-`     |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TimerRestart [#timerrestart]

Restarts the timer. Wraps `TimerActionTrigger` with `action="restart"`.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `hidden`    | `boolean` | `-`     |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### TimerPlay [#timerplay]

Shorthand for a single "go" control: renders `TimerResume` when the timer is `paused`, otherwise `TimerStart`.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `hidden`    | `boolean` | `-`     |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

### `remainingMsUntilDate` [#remainingmsuntildate]

| Parameter | Type   |
| --------- | ------ |
| `date`    | `Date` |

Returns a `number` of milliseconds until `date`, or `0` if `date` is in the past.

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/timer#api-reference).


# Toast (/docs/components/toast)



<ComponentPreview componentName="toast" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/toast
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        , and 

        [Spinner](/docs/components/spinner)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react tailwind-variants
      ```

      <Step>
        Import the following variables into your CSS file
      </Step>

      <CodeCollapsibleWrapper>
        ```css
        @theme inline {
          --color-destructive-foreground: var(--destructive-foreground);
          --color-info: var(--info);
          --color-info-foreground: var(--info-foreground);
          --color-success: var(--success);
          --color-success-foreground: var(--success-foreground);
          --color-warning: var(--warning);
          --color-warning-foreground: var(--warning-foreground);
        }

        :root {
          --destructive-foreground: var(--color-red-700);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-700);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-700);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-700);
        }

        .dark {
          --destructive-foreground: var(--color-red-400);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-400);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-400);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-400);
        }
        ```
      </CodeCollapsibleWrapper>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/toast.tsx" src="/toast.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Toaster } from "@/components/ui/toast";
```

```tsx
const toaster = useToast();

// add the toaster to the layout
<Toaster toaster={toaster} />

// show a toast
toaster.create({
  title: "Show Info Toast",
  description: "This is an info toast",
  type: "info",
});
```

## Deduplication [#deduplication]

Toasts with the same `id` are deduplicated. If no `id` is passed, a new toast is created.

<ComponentPreview componentName="toast" fileName="example-dedupe" />

## Placement [#placement]

<ComponentPreview componentName="toast" fileName="example-placement" />

By default, the toaster is placed at the bottom right corner of the screen.

Update the `placement` option in `createToaster()` to customize the toaster position.

```tsx title="components/ui/toast.tsx" {2} showLineNumbers
const baseToaster = createToaster({
  placement: "bottom-end",
  overlap: true,
  max: 4,
});
```

## Max toasts [#max-toasts]

Any extra toasts will be queued and rendered when a toast has been dismissed.

By default, the toaster displays up to 3 toasts. Update the `max` option in `createToaster()` to change the maximum number of visible toasts.

```tsx title="components/ui/toast.tsx" {4} showLineNumbers
const baseToaster = createToaster({
  placement: "bottom-end",
  overlap: true,
  max: 4,
});
```

## Examples [#examples]

### Variants [#variants]

Use `success`, `error`, `warning`, and `info` for the matching icon and accent color.

You can also pass `type` on `toast.create`.

<ComponentPreview componentName="toast" fileName="example-variants" />

### Promise [#promise]

<ComponentPreview componentName="toast" fileName="example-promise" />

### Action [#action]

<ComponentPreview componentName="toast" fileName="example-action" />

### Duration [#duration]

Control how long a toast stays visible with the `duration` option.

Use `Infinity` to keep the toast visible until the user dismisses it.

<ComponentPreview componentName="toast" fileName="example-duration" />

### Not Closable [#not-closable]

Use `closable` prop to control whether the close button is shown.

<ComponentPreview componentName="toast" fileName="example-closable" />

## API Reference [#api-reference]

### Toaster [#toaster]

Toast container. Place once in your app layout.

| Prop        | Type                               | Default |
| ----------- | ---------------------------------- | ------- |
| `toaster`   | `ReturnType<typeof createToaster>` | `-`     |
| `className` | `string`                           | `-`     |

### toast [#toast]

Toast instance. Used to create and manage toasts.

| Prop          | Type                                                       | Default  |
| ------------- | ---------------------------------------------------------- | -------- |
| `title`       | `string`                                                   | `-`      |
| `description` | `string`                                                   | `-`      |
| `type`        | `"success" \| "error" \| "warning" \| "info" \| "loading"` | `"info"` |
| `duration`    | `number`                                                   | `3000`   |
| `closable`    | `boolean`                                                  | `true`   |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/toast#api-reference).


# Toggle Group (/docs/components/toggle-group)



<ComponentPreview componentName="toggle-group" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/toggle-group
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Toggle](/docs/components/toggle)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/toggle-group.tsx" src="/toggle-group.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
ToggleGroup
└── ToggleGroupItem
```

## Usage [#usage]

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

```tsx
<ToggleGroup>
  <ToggleGroupItem value="1">Item 1</ToggleGroupItem>
  <ToggleGroupItem value="2">Item 2</ToggleGroupItem>
</ToggleGroup>
```

## Controlled [#controlled]

Use the `value` and `onValueChange` props to control the toggle group state programmatically.

<ComponentPreview componentName="toggle-group" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

Disable the entire group with the `disabled` prop.

<ComponentPreview componentName="toggle-group" fileName="example-disabled" />

### With disabled toggle [#with-disabled-toggle]

Disable individual toggles by setting `disabled` on a specific item.

<ComponentPreview componentName="toggle-group" fileName="example-disabled-item" />

## Orientation [#orientation]

Use `orientation` to change the orientation of the toggle group.

### Horizontal [#horizontal]

<ComponentPreview componentName="toggle-group" fileName="example-horizontal" />

### Vertical [#vertical]

<ComponentPreview componentName="toggle-group" fileName="example-vertical" />

## Variant [#variant]

Use `variant` to change the visual style of the toggle buttons.

### Ghost [#ghost]

<ComponentPreview componentName="toggle-group" fileName="example-ghost" />

### Outline [#outline]

<ComponentPreview componentName="toggle-group" fileName="example-outline" />

## Examples [#examples]

### With spacing [#with-spacing]

Use `spacing` to add space between buttons.

<ComponentPreview componentName="toggle-group" fileName="example-spacing" />

### Single selection [#single-selection]

Use `multiple={false}` to allow only one toggle to be selected at a time.

<ComponentPreview componentName="toggle-group" fileName="example-single" />

### Custom toggle group [#custom-toggle-group]

A custom toggle group example with a custom styling for font weight selection.

<ComponentPreview componentName="toggle-group" fileName="example-custom" />

## API Reference [#api-reference]

### ToggleGroup [#togglegroup]

Root component. Provides shared variant and size to child toggles via context.

| Prop            | Type                                                           | Default        |
| --------------- | -------------------------------------------------------------- | -------------- |
| `variant`       | `"outline" \| "ghost"`                                         | `"ghost"`      |
| `size`          | `"sm" \| "md" \| "lg"`                                         | `"md"`         |
| `spacing`       | `"0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10"` | `"0"`          |
| `multiple`      | `boolean`                                                      | `true`         |
| `defaultValue`  | `string[]`                                                     | -              |
| `value`         | `string[]`                                                     | -              |
| `onValueChange` | `(details: ValueChangeDetails) => void`                        | -              |
| `orientation`   | `"horizontal" \| "vertical"`                                   | `"horizontal"` |
| `disabled`      | `boolean`                                                      | `false`        |
| `className`     | `string`                                                       | -              |

| Attribute | Default                                   |
| --------- | ----------------------------------------- |
| `--gap`   | Set from the `spacing` prop (default `0`) |

### ToggleGroupItem [#togglegroupitem]

Single toggle in the group. Uses [Toggle](/docs/components/toggle) internally.

| Prop         | Type      | Default      |
| ------------ | --------- | ------------ |
| `value`      | `string`  | **required** |
| `disabled`   | `boolean` | `false`      |
| `className`  | `string`  | -            |
| `aria-label` | `string`  | -            |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/toggle-group#api-reference).


# Toggle Tooltip (/docs/components/toggle-tooltip)



<Alert>
  <InfoIcon />

  <AlertDescription>
    Toggle Tooltip is built on top of the [Popover](/docs/components/popover) component. Check it out for more examples.
  </AlertDescription>
</Alert>

<ComponentPreview componentName="toggle-tooltip" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/toggle-tooltip
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Popover](/docs/components/popover)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/toggle-tooltip.tsx" src="/toggle-tooltip.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
ToggleTooltip
├── ToggleTooltipTrigger
└── ToggleTooltipContent
```

## Usage [#usage]

```tsx
import {
  ToggleTooltip,
  ToggleTooltipContent,
  ToggleTooltipTrigger,
} from "@/components/ui/toggle-tooltip";
```

```tsx
<ToggleTooltip>
  <ToggleTooltipTrigger />
  <ToggleTooltipContent>
    Hover or click to see this content.
  </ToggleTooltipContent>
</ToggleTooltip>
```

## Tooltip vs Toggle Tooltip [#tooltip-vs-toggle-tooltip]

You're viewing **Toggle Tooltip**—a popover that opens on hover or click. Use it when the content is essential and should be accessible to everyone, including touch users and screen readers.

### Use Toggle Tooltip when [#use-toggle-tooltip-when]

* The trigger's **primary purpose** is to reveal the content.
* The content is **essential** and should be accessible to touch users and screen readers.
* You need **click-to-open** so everyone can access it—no hover required.
* The content may be **interactive** (links, buttons) since Toggle Tooltip is a popover under the hood.

### Toggle Tooltip behavior [#toggle-tooltip-behavior]

* **Touch and keyboard** — Opens on click as well as hover, so touch and keyboard users can access the content.
* **Screen reader exposure** — Content is exposed to assistive technologies.
* **Escape to close** — Press Escape to dismiss when open.
* **Icon-only triggers** — Add an `aria-label` when the trigger is an icon without visible text.

### Consider Tooltip when [#consider-tooltip-when]

* The trigger has its own purpose and the popup is **supplementary**.
* The content is **non-essential**—nice-to-have clarity.
* Touch users don't need to access it—tooltips only open on hover/focus.
* The content is **short and non-interactive** (no links or buttons inside).

## Positioning [#positioning]

Use the `positioning` prop to change the position.

<ComponentPreview componentName="toggle-tooltip" fileName="example-side" />

## API Reference [#api-reference]

### ToggleTooltip [#toggletooltip]

Root component. Combines toggle with tooltip on click.

| Prop            | Type                                   | Default                |
| --------------- | -------------------------------------- | ---------------------- |
| `positioning`   | `PositioningOptions`                   | `{ placement: "top" }` |
| `modal`         | `boolean`                              | `false`                |
| `lazyMount`     | `boolean`                              | `true`                 |
| `unmountOnExit` | `boolean`                              | `true`                 |
| `open`          | `boolean`                              | -                      |
| `onOpenChange`  | `(details: OpenChangeDetails) => void` | -                      |

### ToggleTooltipTrigger [#toggletooltiptrigger]

Shows the tooltip on click. Button by default; use `asChild` for custom elements.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### ToggleTooltipContent [#toggletooltipcontent]

Tooltip content shown in a popover on click.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### ToggleTooltipArrow [#toggletooltiparrow]

Optional arrow pointing to the trigger. Place inside `ToggleTooltipContent`.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

| Attribute            | Default                      |
| -------------------- | ---------------------------- |
| `--arrow-background` | `var(--foreground)`          |
| `--arrow-size`       | `calc(1.5 * var(--spacing))` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/popover#api-reference).


# Toggle (/docs/components/toggle)



<ComponentPreview componentName="toggle" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/toggle
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/toggle.tsx" src="/toggle.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { 
  Toggle,   
  ToggleIndicator 
} from "@/components/ui/toggle"; 
```

```tsx
<Toggle>
  <ToggleIndicator />
</Toggle>
```

## Controlled [#controlled]

Use the `pressed` and `onPressedChange` props to control the toggle state programmatically.

<ComponentPreview componentName="toggle" fileName="example-controlled" />

## States [#states]

### Disabled [#disabled]

Use the `disabled` prop to disable the toggle.

<ComponentPreview componentName="toggle" fileName="example-disabled" />

## Variants [#variants]

### Default [#default]

<ComponentPreview componentName="toggle" fileName="example-default" />

### Outline [#outline]

<ComponentPreview componentName="toggle" fileName="example-outline" />

## Sizes [#sizes]

### Small [#small]

<ComponentPreview componentName="toggle" fileName="example-size-sm" />

### Medium [#medium]

<ComponentPreview componentName="toggle" fileName="example-size-md" />

### Large [#large]

<ComponentPreview componentName="toggle" fileName="example-size-lg" />

## Examples [#examples]

### Icon Group [#icon-group]

Use multiple toggles with icons for toolbar-style controls.

<ComponentPreview componentName="toggle" fileName="example-icon-group" />

## API Reference [#api-reference]

### Toggle [#toggle]

Toggle button for on/off or selected state. Use `asChild` for custom elements.

| Prop              | Type                                      | Default   |
| ----------------- | ----------------------------------------- | --------- |
| `variant`         | `"outline" \| "ghost"`                    | `"ghost"` |
| `size`            | `"sm" \| "md" \| "lg"`                    | `"md"`    |
| `pressed`         | `boolean`                                 | `-`       |
| `defaultPressed`  | `boolean`                                 | `false`   |
| `disabled`        | `boolean`                                 | `false`   |
| `onPressedChange` | `(details: PressedChangeDetails) => void` | `-`       |
| `className`       | `string`                                  | `-`       |
| `asChild`         | `boolean`                                 | `false`   |

### ToggleIndicator [#toggleindicator]

Icon or indicator shown when toggle is active. Omitted when used as child.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | `-`     |
| `asChild`   | `boolean` | `false` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/toggle#api-reference).


# Tooltip (/docs/components/tooltip)



<ComponentPreview componentName="tooltip" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/tooltip
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/tooltip.tsx" src="/tooltip.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Tooltip
├── TooltipTrigger
└── TooltipContent
```

## Usage [#usage]

```tsx
import { 
  Tooltip, 
  TooltipContent, 
  TooltipTrigger 
} from "@/components/ui/tooltip";
```

```tsx
<Tooltip>
  <TooltipTrigger>Hover me</TooltipTrigger>
  <TooltipContent>
    {/* Content */}
  </TooltipContent>
</Tooltip>
```

## Tooltip vs Toggle Tooltip [#tooltip-vs-toggle-tooltip]

You're viewing **Tooltip**—a label that shows on hover or focus. Use it when the content is supplementary and non-essential, and you're okay with touch users not having access.

### Use Tooltip when [#use-tooltip-when]

* The trigger has its own purpose and the popup is **supplementary**.
* The content is **non-essential**—nice-to-have clarity for sighted mouse/keyboard users.
* You're okay with **touch users not seeing it**—tooltips only open on hover/focus, not on tap.
* The content is **short and non-interactive** (no links or buttons inside).

### Tooltip behavior [#tooltip-behavior]

* **Hover or focus only** — Opens on hover/focus; touch users cannot access it.
* **Non-interactive** — Keep content short with no links or buttons.
* **Supplementary** — Best for nice-to-have information, not critical content.

### Consider Toggle Tooltip when [#consider-toggle-tooltip-when]

* The trigger's **primary purpose** is to reveal the content.
* The content is **essential** and should be accessible to touch users and screen readers.
* You need **click-to-open** so everyone can access it.
* The content may be **interactive** (links, buttons).

## Positioning [#positioning]

Use the `positioning` prop to change the position of the tooltip.

<ComponentPreview componentName="tooltip" fileName="example-side" />

## Examples [#examples]

### With Keyboard Shortcut [#with-keyboard-shortcut]

<ComponentPreview componentName="tooltip" fileName="example-with-keyboard-shortcut" />

### Disabled Button [#disabled-button]

Show a tooltip on a disabled button by wrapping it with a span.

<ComponentPreview componentName="tooltip" fileName="example-disabled-button" />

## API Reference [#api-reference]

### Tooltip [#tooltip]

Root component that wraps the tooltip. Manages open state and positioning.

| Prop                 | Type                                   | Default                |
| -------------------- | -------------------------------------- | ---------------------- |
| `positioning`        | `PositioningOptions`                   | `{ placement: "top" }` |
| `openDelay`          | `number`                               | `0`                    |
| `closeDelay`         | `number`                               | `100`                  |
| `lazyMount`          | `boolean`                              | `true`                 |
| `unmountOnExit`      | `boolean`                              | `true`                 |
| `open`               | `boolean`                              | -                      |
| `defaultOpen`        | `boolean`                              | -                      |
| `onOpenChange`       | `(details: OpenChangeDetails) => void` | -                      |
| `disabled`           | `boolean`                              | -                      |
| `interactive`        | `boolean`                              | `false`                |
| `closeOnClick`       | `boolean`                              | `true`                 |
| `closeOnEscape`      | `boolean`                              | `true`                 |
| `closeOnPointerDown` | `boolean`                              | `true`                 |
| `closeOnScroll`      | `boolean`                              | `true`                 |

### TooltipTrigger [#tooltiptrigger]

Element that shows the tooltip on hover or focus. Button by default; use `asChild` for custom elements.

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | -       |

### TooltipContent [#tooltipcontent]

Tooltip content shown in a popover on hover or focus.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `className` | `string`  | -       |
| `asChild`   | `boolean` | -       |

### TooltipArrow [#tooltiparrow]

Optional arrow pointing to the trigger. Place inside `TooltipContent`.

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | -       |

| Attribute            | Default                      |
| -------------------- | ---------------------------- |
| `--arrow-background` | `var(--foreground)`          |
| `--arrow-size`       | `calc(1.5 * var(--spacing))` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/tooltip#api-reference).


# Tour (/docs/components/tour)



<ComponentPreview componentName="tour" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/tour
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Button](/docs/components/button)

         and 

        [Dialog](/docs/components/dialog)

        . Install them first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/tour.tsx" src="/tour.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
Tour
├── TourTrigger
├── TourActionTrigger
├── TourOverlay
└── TourContent
    ├── TourSpotlight
    ├── TourHeader
    │   ├── TourProgressText
    │   ├── TourTitle
    │   └── TourDescription
    ├── TourBody
    ├── TourFooter
    │   ├── TourActions
    │   ├── TourPreviousStep
    │   └── TourNextStep
    └── TourClose
```

## Usage [#usage]

```tsx
import { 
  Tour, 
  TourTrigger, 
  TourContent, 
  TourHeader,
  TourProgressText,
  TourTitle,
  TourDescription,
  TourFooter,
  TourNextStep,
  TourPreviousStep,
} from "@/components/ui/tour";
```

```tsx
<Tour steps={steps}>
  <TourTrigger>Open Tour</TourTrigger>
  <TourContent>
    <TourHeader>
      <TourProgressText />
      <TourTitle />
      <TourDescription />
    </TourHeader>
  </TourContent>
  <TourFooter>
    <TourNextStep />
    <TourPreviousStep />
  </TourFooter>
</Tour>
```

## Examples [#examples]

### Step Types [#step-types]

Demonstrate all three step types in a single tour: `dialog` for welcome/completion, `tooltip` anchored to elements, and `floating` for fixed-position content.

<ComponentPreview componentName="tour" fileName="example-step-types" />

### Progress [#progress]

Display a visual progress indicator at the bottom of the tour content showing how far along the user is.

<ComponentPreview componentName="tour" fileName="example-progress" />

### Skip [#skip]

Allow users to skip the entire tour at any step by adding a skip action.

<ComponentPreview componentName="tour" fileName="example-skip" />

### Keyboard Navigation [#keyboard-navigation]

Enable arrow key navigation between tour steps using the `keyboardNavigation` prop.

<ComponentPreview componentName="tour" fileName="example-keyboard-navigation" />

### Events [#events]

Listen to tour lifecycle events like `onStepChange` and `onStatusChange` to track user progress.

<ComponentPreview componentName="tour" fileName="example-events" />

### Wait for Click [#wait-for-click]

Use the `effect` function with `waitForEvent` to wait for user interaction before proceeding to the next step.

<ComponentPreview componentName="tour" fileName="example-wait-for-click" />

### Wait for Input [#wait-for-input]

Create form tutorials that wait for users to enter valid input before advancing.

<ComponentPreview componentName="tour" fileName="example-wait-for-input" />

### Wait for Element [#wait-for-element]

Wait for dynamically rendered elements to appear in the DOM before showing a step.

<ComponentPreview componentName="tour" fileName="example-wait-for-element" />

### Async [#async]

Load data asynchronously and update step content before displaying it using the `effect` function with `show()` and `update()`.

<ComponentPreview componentName="tour" fileName="example-async" />

### Custom spacing [#custom-spacing]

Use `[--space:--spacing("value")]` on `TourContent` to adjust internal spacing.

Default spacing is `--spacing(4)`.

<ComponentPreview componentName="tour" fileName="example-custom-spacing" />

> You can use breakpoint utilities to change the internal spacing at different screen sizes.

```css
  md:[--space:--spacing(6)] lg:[--space:--spacing(8)]
```

## API Reference [#api-reference]

### Tour [#tour]

| Prop                 | Type                                            | Default |
| -------------------- | ----------------------------------------------- | ------- |
| `steps`              | `TourStepDetails[]`                             | `[]`    |
| `lazyMount`          | `boolean`                                       | `true`  |
| `unmountOnExit`      | `boolean`                                       | `true`  |
| `keyboardNavigation` | `boolean`                                       | -       |
| `onStepChange`       | `(details: { stepId: string \| null }) => void` | -       |
| `onStatusChange`     | `(details: { status: string }) => void`         | -       |
| `immediate`          | `boolean`                                       | -       |
| `present`            | `boolean`                                       | -       |
| `onExitComplete`     | `() => void`                                    | -       |

### TourTrigger [#tourtrigger]

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### TourContent [#tourcontent]

| Prop              | Type      | Default |
| ----------------- | --------- | ------- |
| `showCloseButton` | `boolean` | `true`  |
| `className`       | `string`  | -       |
| `asChild`         | `boolean` | -       |

| Attribute | Default        |
| --------- | -------------- |
| `--space` | `--spacing(4)` |

### TourHeader [#tourheader]

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### TourTitle [#tourtitle]

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### TourDescription [#tourdescription]

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### TourProgressText [#tourprogresstext]

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### TourFooter [#tourfooter]

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### TourActions [#touractions]

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### TourPreviousStep [#tourpreviousstep]

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | -       |

### TourNextStep [#tournextstep]

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | -       |

### TourClose [#tourclose]

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | -       |

### useTourContext [#usetourcontext]

| Return        | Type            |
| ------------- | --------------- |
| `tour`        | `UseTourReturn` |
| `handleStart` | `() => void`    |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/tour#api-reference).


# Tree View (/docs/components/tree-view)



<ComponentPreview componentName="tree-view" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/tree-view
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This component depends on 

        [Checkbox](/docs/components/checkbox)

        . Install it first if you haven't already.
      </Step>

      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants lucide-react
      ```

      <Step>
        Add the following to your 

        `globals.css`

         for the tree-view expand/collapse animation:
      </Step>

      ```css title="globals.css"
      @theme inline {
        @keyframes expand {
          from { height: var(--collapsed-height, 0); }
          to { height: var(--height); }
        }
        @keyframes collapse {
          from { height: var(--height); }
          to { height: var(--collapsed-height, 0); }
        }
      }
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/tree-view.tsx" src="/tree-view.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Anatomy [#anatomy]

```text
TreeView
├── TreeViewLabel
└── TreeViewTree
    └── TreeViewNode
        ├── TreeViewBranch
        │   ├── TreeViewBranchItem
        │   │   └── TreeViewBranchIndicator
        │   └── TreeViewBranchContent
        │       └── TreeViewNode …
        └── TreeViewContent
            └── TreeViewItem
                └── TreeViewCheckbox
```

## Usage [#usage]

```tsx
import {
  TreeView,
  TreeViewLabel,
  TreeViewTree,
  TreeViewNode,
  TreeViewBranch,
  TreeViewBranchItem,
  TreeViewBranchContent,
  TreeViewContent,
  TreeViewItem,
  createTreeCollection,
} from "@/components/ui/tree-view";
```

```tsx
const collection = createTreeCollection({
  rootNode: { id: "ROOT", name: "", children: [...] },
});

const Example = () => (
  <TreeView collection={collection}>
    <TreeViewTree>
      {collection.rootNode.children?.map((node, index) => (
        <TreeNode indexPath={[index]} key={node.id} node={node} />
      ))}
    </TreeViewTree>
  </TreeView>
)

const TreeNode = (props: React.ComponentProps<typeof TreeViewNode>) => {
  const { node, indexPath } = props;

  return (
    <TreeViewNode indexPath={indexPath} key={node.id} node={node}>
      {node.children ? (
        <TreeViewBranch>
          <TreeViewBranchItem>{node.name}</TreeViewBranchItem>
          <TreeViewBranchContent>
            {node.children.map((child, index) => (
              <TreeNode indexPath={[...indexPath, index]} key={child.id} node={child} />
            ))}
          </TreeViewBranchContent>
        </TreeViewBranch>
      ) : (
        <TreeViewContent>
          <TreeViewItem>{node.name}</TreeViewItem>
        </TreeViewContent>
      )}
    </TreeViewNode>
  );
};
```

## Controlled [#controlled]

Use `selectedValue` and `onSelectionChange` to control the selected node and react to selection changes.

<ComponentPreview componentName="tree-view" fileName="example-controlled" />

## Examples [#examples]

### Multiple selection [#multiple-selection]

Use `selectionMode="multiple"` to allow selecting multiple nodes.

Hold `Shift` and `click` to select a range, or use `Ctrl`/`Cmd`+`click` to toggle individual nodes.

<ComponentPreview componentName="tree-view" fileName="example-multiple-selection" />

### With Context Menu [#with-context-menu]

Right-click on tree items to show a context menu.

<ComponentPreview componentName="tree-view" fileName="example-context-menu" />

### Renaming nodes [#renaming-nodes]

Use the `canRename` prop and `onRenameComplete` callback to enable inline renaming of nodes. Press F2 to activate rename mode on the focused node.

<ComponentPreview componentName="tree-view" fileName="example-rename" />

### With checkboxes [#with-checkboxes]

Use the `checkedValue` and `onCheckedChange` props to control the checked nodes.

<ComponentPreview componentName="tree-view" fileName="example-checkbox-tree" />

### Links [#links]

Tree items can be rendered as links. Use `asChild` on `TreeViewContent` and wrap an `<a>` element with `TreeViewItem` inside.

<ComponentPreview componentName="tree-view" fileName="example-links" />

### Mini Editor [#mini-editor]

Use the tree view to create a file editor.

<ComponentPreview componentName="tree-view" fileName="example-editor" />

## Custom icons [#custom-icons]

There are three ways to customize icons:

1. **Folder** — `icon` and `expandedIcon` props on `TreeViewBranchItem`, or per-node via `TreeNodeType`
2. **Single item** — `icon` prop on `TreeViewItem`
3. **By extension** — `fileIcons` prop on `TreeView` with `createFileIcons`

### Folder icons [#folder-icons]

Use the `icon` and `expandedIcon` props on `TreeViewBranchItem` to customize folder icons. Pass `null` to hide the icon.

<ComponentPreview componentName="tree-view" fileName="example-custom-icons-folder" />

### Single item icon [#single-item-icon]

Pass the `icon` prop to `TreeViewItem` to override the icon for a specific leaf node.

<ComponentPreview componentName="tree-view" fileName="example-custom-icons-item" />

### With file extensions [#with-file-extensions]

Use the `fileIcons` prop on `TreeView` with `createFileIcons` to map file extensions to icon components. Icons are resolved from each node's id; unmatched extensions fall back to `FileIcon`.

<ComponentPreview componentName="tree-view" fileName="example-custom-icons" />

## API Reference [#api-reference]

### TreeView [#treeview]

Root component. Provides tree context and manages expand/selection state.

| Prop                   | Type                                            | Default      |
| ---------------------- | ----------------------------------------------- | ------------ |
| `collection`           | `TreeCollection`                                | **required** |
| `fileIcons`            | `Record<string, React.JSX.ElementType \| null>` | -            |
| `selectedValue`        | `string[]`                                      | -            |
| `checkedValue`         | `string[]`                                      | -            |
| `onCheckedChange`      | `(details: CheckedChangeDetails) => void`       | -            |
| `canRename`            | `(details: RenameDetails) => boolean`           | -            |
| `onRenameComplete`     | `(details: RenameCompleteDetails) => void`      | -            |
| `defaultSelectedValue` | `string[]`                                      | -            |
| `onSelectionChange`    | `(details: SelectionChangeDetails) => void`     | -            |
| `expandedValue`        | `string[]`                                      | -            |
| `defaultExpandedValue` | `string[]`                                      | -            |
| `onExpandedChange`     | `(details: ExpandedChangeDetails) => void`      | -            |
| `selectionMode`        | `"single" \| "multiple"`                        | `"single"`   |
| `lazyMount`            | `boolean`                                       | `true`       |
| `unmountOnExit`        | `boolean`                                       | `true`       |
| `className`            | `string`                                        | -            |

| Attribute          | Default          |
| ------------------ | ---------------- |
| `--indentation`    | `--spacing(4)`   |
| `--item-gap`       | `--spacing(2)`   |
| `--padding-block`  | `--spacing(1.5)` |
| `--padding-inline` | `--spacing(3)`   |
| `--icon-size`      | `--spacing(4)`   |

### TreeViewLabel [#treeviewlabel]

Accessible label for the tree.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | -       |

### TreeViewTree [#treeviewtree]

Wraps the root-level tree nodes.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | -       |

### TreeViewNode [#treeviewnode]

Provides tree node context. Must wrap each branch or item.

| Prop        | Type           | Default      |
| ----------- | -------------- | ------------ |
| `node`      | `TreeNodeType` | **required** |
| `indexPath` | `number[]`     | **required** |
| `className` | `string`       | -            |

### TreeViewBranch [#treeviewbranch]

Expandable branch with children. Toggles open/closed.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | -       |

### TreeViewBranchItem [#treeviewbranchitem]

Clickable area to expand or collapse a branch.

| Prop           | Type                            | Default          |
| -------------- | ------------------------------- | ---------------- |
| `asChild`      | `boolean`                       | `false`          |
| `icon`         | `React.JSX.ElementType \| null` | `FolderIcon`     |
| `expandedIcon` | `React.JSX.ElementType \| null` | `FolderOpenIcon` |
| `className`    | `string`                        | -                |

### TreeViewBranchContent [#treeviewbranchcontent]

Holds the branch children. Shown when expanded.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | -       |

### TreeViewContent [#treeviewcontent]

Wrapper for leaf (non-expandable) items.

| Prop        | Type      | Default |
| ----------- | --------- | ------- |
| `asChild`   | `boolean` | `false` |
| `className` | `string`  | -       |

### TreeViewItem [#treeviewitem]

Leaf node (non-expandable). The `icon` prop is fallback when no `fileIcons` match.

| Prop        | Type                    | Default    |
| ----------- | ----------------------- | ---------- |
| `icon`      | `React.JSX.ElementType` | `FileIcon` |
| `className` | `string`                | -          |

### TreeViewCheckbox [#treeviewcheckbox]

Checkbox for selecting a node in multi-select mode.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### createTreeCollection [#createtreecollection]

Creates a tree collection from node data. Use with `collection` prop on `TreeView`.

**Options**

| Prop           | Type                     | Default               |
| -------------- | ------------------------ | --------------------- |
| `rootNode`     | `T extends TreeNodeType` | **required**          |
| `nodeToValue`  | `(node: T) => string`    | `(node) => node.id`   |
| `nodeToString` | `(node: T) => string`    | `(node) => node.name` |

**TreeNodeType** — Shape of each node (extend with generic `T` for custom props):

| Property       | Type                            | Default     |
| -------------- | ------------------------------- | ----------- |
| `id`           | `string`                        | -           |
| `name`         | `string`                        | -           |
| `children`     | `TreeNodeType<T>[]`             | `undefined` |
| `icon`         | `React.JSX.ElementType \| null` | `undefined` |
| `expandedIcon` | `React.JSX.ElementType \| null` | `undefined` |

```tsx
const collection = createTreeCollection({
  rootNode: { id: "ROOT", name: "", children: [...] },
});

// With custom node props
type LinkNode = TreeNodeType & { href?: string };
const links = createTreeCollection<LinkNode>({
  rootNode: {
    id: "docs",
    name: "Docs",
    children: [{ id: "intro", name: "Intro", href: "/intro" }],
  },
});
```

### createFileIcons [#createfileicons]

Creates a type-safe mapping of file extensions to icon components. Use with `fileIcons` prop on `TreeView`.

Keys use dotted extensions.

```tsx
const fileIcons = createFileIcons({
  ".tsx": FileCode,
  ".json": FileJson,
  ".md": FileText,
});
```

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/tree-view#api-reference).


# Formisch (/docs/forms/formisch)



This guide will cover building forms using the [Field](/docs/components/field) component, adding schema validation with [Valibot](https://valibot.dev), handling errors, ensuring accessibility, and more.

## Demo [#demo]

We’ll build a form with a text input and textarea. When you submit, the form data is validated and any errors will be shown.

<Alert>
  <InfoIcon />

  <AlertTitle>
    Browser validation disabled
  </AlertTitle>

  <AlertDescription>
    For the purposes of this demo, browser validation is disabled to illustrate schema validation. In production, keep native validation enabled when appropriate.
  </AlertDescription>
</Alert>

<ComponentPreview componentName="form/formisch" fileName="example-demo" showBorders="false" hasMaxHeight="false" />

## Approach [#approach]

This form uses Formisch for state and Valibot for validation. We'll build forms using the `Field` component, which gives you complete flexibility over the markup and styling.

* Uses Formisch's `useForm` hook for form state management.
* Uses the `Form` component for submit handling.
* Import Formisch’s `Field` under an alias (`FormischField`) for controlled inputs.
* Uses Shark `Field` components for building accessible forms.
* Uses client-side validation by passing your Valibot schema into `schema`.

## Anatomy [#anatomy]

Typical structure: wrap each field with `FormischField`, and the `Field` component.

```tsx showLineNumbers {5-12}
<Form of={form} onSubmit={onSubmit}>
  <FieldGroup>
    <FormischField of={form} path={["title"]}>
      {(field) => (
        <Field invalid={Boolean(field.errors?.length)}>
          <FieldLabel>Bug Title</FieldLabel>
          <Input {...field.props} value={field.input} />
           <FieldDescription>
            Provide a concise title for your bug report.
          </FieldDescription>
          <FieldError>{field.errors?.[0]}</FieldError>
        </Field>
      )}
    </FormischField>
  </FieldGroup>
  <Button type="submit">Submit</Button>
</Form>
```

## Form [#form]

### Create a schema [#create-a-schema]

Define your form shape with a Valibot schema.

<Alert>
  <InfoIcon />

  <AlertDescription>
    **Note:** Formisch only supports [Valibot](https://formisch.dev/react/guides/installation/#install-valibot) for validation.
  </AlertDescription>
</Alert>

<ComponentSource src="../examples/form/formisch/example-schema-bug-report.ts" language="ts" />

### Setup [#setup]

* Create the form with `useForm` from Formisch and pass your schema to the `schema` option,
* Wrap fields in `Form` and pass the form to the `onSubmit` option.

```tsx showLineNumbers title="form.tsx" {9-15,18-20}
import { Form, Field as FormischField, useForm } from "@formisch/react";
import * as v from "valibot";

const formSchema = v.object({
  // ...
});

export const BugReportForm = () => {
  const form = useForm({
    schema: formSchema,
    initialInput: {
      title: "",
      description: "",
    },
  });

  return (
    <Form of={form} onSubmit={(output) => console.log(output)}>
      {/* Build the form here */}
    </Form>
  );
};
```

### Build [#build]

Build the form using the `FormischField` from Formisch and the Shark `Field`.

<ComponentSource src="../examples/form/formisch/example-demo.tsx" />

### Done [#done]

That's it. You now have a fully accessible form with client-side validation.

When you submit the form, the `onSubmit` handler on `Form` receives validated output. If the form data is invalid, Formisch will display the errors on `field.errors` for `FieldError`.

## Validation [#validation]

### Client-side [#client-side]

Formisch validates your form data using the Valibot schema. Define a schema and pass it to the `schema` option of the `useForm` hook.

```tsx showLineNumbers title="example-form.tsx" {4-7,11}
import { useForm } from "@formisch/react"
import * as v from "valibot"

const formSchema = v.object({
  title: v.string(),
  description: v.optional(v.string()),
})

export const ExampleForm = () => {
  const form = useForm({
    schema: formSchema,
    initialInput: {
      title: "",
      description: "",
    },
  })
}
```

### Modes [#modes]

Configure when validation runs via the `validate` and `revalidate` options:

```tsx showLineNumbers title="form.tsx" {3-4}
const form = useForm({
  schema: formSchema,
  validate: "submit",
  revalidate: "input",
})
```

| Option      | Role                                   |
| ----------- | -------------------------------------- |
| `"initial"` | Validation triggers on initial render. |
| `"touch"`   | Validation triggers on field touch.    |
| `"input"`   | Validation triggers on field input.    |
| `"change"`  | Validation triggers on field change.   |
| `"blur"`    | Validation triggers on field blur.     |
| `"submit"`  | Validation triggers on form submit.    |

## Displaying Errors [#displaying-errors]

Display errors next to the field using `FieldError`. For styling and accessibility:

* Add the `invalid` prop to the `Field` component.
* Don't need to add the `invalid` prop to the form control such as `Input`, `Checkbox`, etc.

```tsx showLineNumbers title="form.tsx" {3,6}
<FormischField of={form} path={["email"]}>
  {(field) => (
    <Field invalid={Boolean(field.errors?.length)}>
      <FieldLabel>Email</FieldLabel>
      <Input {...field.props} type="email" value={field.input} />
      <FieldError>{field.errors?.[0]}</FieldError>
    </Field>
  )}
</FormischField>
```

## Different types of fields [#different-types-of-fields]

### Input [#input]

* Spread `field.props` on `Input` and set `value={field.input}`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-input" showBorders="false" hasMaxHeight="false" />

### Textarea [#textarea]

* Spread `field.props` on `Textarea` and set `value={field.input}`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-textarea" showBorders="false" hasMaxHeight="false" />

### NativeSelect [#nativeselect]

* Spread `field.props` on `NativeSelect` and set `value={field.input}`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-native-select" showBorders="false" hasMaxHeight="false" />

### Select [#select]

* Wire `field.input` and `field.onChange` to `Select`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-select" showBorders="false" hasMaxHeight="false" />

### Checkbox [#checkbox]

* Wire `field.input` and `field.onChange` to `Checkbox`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.
* Remember to add `data-slot="checkbox-group"` to the `FieldGroup` component for proper styling and spacing.

<ComponentPreview componentName="form/formisch" fileName="example-checkbox" showBorders="false" hasMaxHeight="false" />

### Radio group [#radio-group]

* Wire `field.input` and `field.onChange` to `RadioGroup`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-radio-group" showBorders="false" hasMaxHeight="false" />

### Switch [#switch]

* Wire `field.input` and `field.onChange` to `Switch`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-switch" showBorders="false" hasMaxHeight="false" />

### NumberInput [#numberinput]

* Wire `field.input` and `field.onChange` to `NumberInput`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-number-input" showBorders="false" hasMaxHeight="false" />

### Slider [#slider]

* Wire `field.input` and `field.onChange` to `Slider`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-slider" showBorders="false" hasMaxHeight="false" />

### Combobox [#combobox]

* Wire `field.input` and `field.onChange` to `Combobox`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-combobox" showBorders="false" hasMaxHeight="false" />

### Autocomplete [#autocomplete]

* Wire `field.input` and `field.onChange` to `Autocomplete`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-autocomplete" showBorders="false" hasMaxHeight="false" />

### Date Picker [#date-picker]

* Wire `field.input` and `field.onChange` to `DatePicker`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-date-picker" showBorders="false" hasMaxHeight="false" />

### Input OTP [#input-otp]

* Wire `field.input` and `field.onChange` to `InputOTP`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-input-otp" showBorders="false" hasMaxHeight="false" />

### Rating [#rating]

* Use `field.onChange` with `Rating`’s `onValueChange` and bind `value` from `field.input`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-rating" showBorders="false" hasMaxHeight="false" />

### File Upload [#file-upload]

* Use `FileUpload` `onFileAccept` to push files into the field value (`field.onChange`).
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/formisch" fileName="example-file-upload" showBorders="false" hasMaxHeight="false" />

### Complex Forms [#complex-forms]

Here is an example of a more complex form with multiple fields and validation.

<ComponentPreview componentName="form/formisch" fileName="example-complex" showBorders="false" hasMaxHeight="false" />

## Resetting the Form [#resetting-the-form]

Import `reset` and pass the form to reset the form to its default values.

```tsx showLineNumbers
import { reset } from "@formisch/react";

<Button
  type="button"
  variant="outline"
  onClick={() => reset(form)}
>
  Reset
</Button>
```

## Array Fields [#array-fields]

Formisch provides a `FieldArray` component for managing dynamic array fields. Also provides helpers like `insert` and `remove` for dynamic lists. This is useful when you need to add or remove fields dynamically.

<ComponentPreview componentName="form/formisch" fileName="example-array-emails" showBorders="false" hasMaxHeight="false" />

### Array Field Structure [#array-field-structure]

Use `FieldArray` component and pass the form to the `of` prop.

```tsx showLineNumbers title="form.tsx" {9-15}
import { FieldArray, Field as FormischField, useForm } from "@formisch/react";

export const ExampleForm = () => {
  const form = useForm({
    // ... form config
  });

  return (
    <FieldArray of={form} path={["emails"]}>
      {(arrayField) => (
        arrayField.items.map((itemId, index) => (
          // Nested field for each array item
        ))
      )}
    </FieldArray>
  );
}
```

### Nested Fields [#nested-fields]

Use `arrayField.items` to render each nested field, passing the correct path for each item.

```tsx showLineNumbers title="form.tsx"
{
  arrayField.items.map((itemId, index) => (
    <FormischField 
      key={itemId} 
      of={form} 
      path={["emails", index, "contact", "address"]}
    >
      {(field) => (
        <Field invalid={Boolean(field.errors?.length)} orientation="horizontal">
          <FieldContent>
            <InputGroup>
              <InputGroupInput
                {...field.props}
                autoComplete="email"
                onChange={(e) => field.onChange(e.target.value)}
                placeholder="name@example.com"
                type="email"
                value={field.input}
              />
              {arrayField.items.length > 1 && (
                <InputGroupAddon align="inline-end">
                  <InputGroupButton
                    aria-label={`Remove email ${String(index + 1)}`}
                    onClick={() =>
                      remove(form, { path: ["emails"], at: index })
                    }
                    size="icon-xs"
                    type="button"
                    variant="ghost"
                  >
                    <XIcon aria-hidden className="size-4" />
                  </InputGroupButton>
                </InputGroupAddon>
              )}
            </InputGroup>
            <FieldError>{field.errors?.[0]}</FieldError>
          </FieldContent>
        </Field>
      )}
    </FormischField>
  ))
}
```

### Adding items [#adding-items]

* Use `insert` to add a new array item.
* Provide `initialInput` matching the nested structure of the array element.

```tsx showLineNumbers title="form.tsx"
import { insert } from "@formisch/react";

<Button
  type="button"
  variant="outline"
  size="sm"
  onClick={() =>
    insert(form, {
      path: ["emails"],
      initialInput: { contact: { address: "" } },
    })
  }
  disabled={arrayField.items.length >= 5}
>
  Add Email Address
</Button>
```

### Removing items [#removing-items]

Use `remove` with the array path and index.

```tsx showLineNumbers title="form.tsx"
import { remove } from "@formisch/react";

{
  arrayField.items.length > 1 && (
    <InputGroupAddon align="inline-end">
      <InputGroupButton
        type="button"
        variant="ghost"
        size="icon-xs"
        onClick={() => remove(form, { path: ["emails"], at: index })}
        aria-label={`Remove email ${index + 1}`}
      >
        <XIcon />
      </InputGroupButton>
    </InputGroupAddon>
  );
}
```

### Array validation [#array-validation]

Use Valibot's `array` method to validate array fields.

```tsx showLineNumbers title="form.tsx"
import * as v from "valibot";

const formSchema = v.object({
  emails: v.pipe(
    v.array(
      v.object({
        contact: v.object({
          address: v.pipe(
            v.string(),
            v.nonEmpty("Enter an email address."),
            v.email("Enter a valid email address.")
          ),
        }),
      })
    ),
    v.minLength(1, "Add at least one email address."),
    v.maxLength(5, "You can add up to 5 email addresses.")
  ),
});
```


# React Hook Form (/docs/forms/react-hook-form)



This guide will cover building forms using the [Field](/docs/components/field) component, adding schema validation with [Zod](https://zod.dev), handling errors, ensuring accessibility, and more.

## Demo [#demo]

We’ll build a form with a text input and textarea. When you submit, the form data is validated and any errors will be shown.

<Alert>
  <InfoIcon />

  <AlertTitle>
    Browser validation disabled
  </AlertTitle>

  <AlertDescription>
    For the purposes of this demo, browser validation is disabled to illustrate schema validation. In production, keep native validation enabled when appropriate.
  </AlertDescription>
</Alert>

<ComponentPreview componentName="form/rhf" fileName="example-demo" showBorders="false" hasMaxHeight="false" />

## Approach [#approach]

This form uses React Hook Form for state and Zod for validation. We'll build forms using the `Field` component, which gives you complete flexibility over the markup and styling.

* Uses React Hook Form's useForm hook for form state management.
* Uses the `Controller` component for controlled inputs.
* Uses the `Field` components for building accessible forms.
* Uses client-side validation by passing your Zod schema into `resolver`.

## Anatomy [#anatomy]

Typical structure: wrap each field with `Controller`, and the `Field` component.

```tsx showLineNumbers {7-18}
<form onSubmit={form.handleSubmit(onSubmit)}>
  <FieldGroup>
    <Controller
      name="title"
      control={form.control}
      render={({ field, fieldState }) => (
        <Field invalid={fieldState.invalid}>
          <FieldLabel>Bug Title</FieldLabel>
          <Input
            {...field}
            placeholder="Login button not working on mobile"
            autoComplete="off"
          />
          <FieldDescription>
            Provide a concise title for your bug report.
          </FieldDescription>
          <FieldError>{fieldState.error?.message}</FieldError>
        </Field>
      )}
    />
  </FieldGroup>
  <Button type="submit">Submit</Button>
</form>
```

## Form [#form]

### Create a schema [#create-a-schema]

Define your form shape with a Zod schema.

<Alert>
  <InfoIcon />

  <AlertDescription>
    **Note:** React Hook Form supports other [Standard Schema](https://react-hook-form.com/get-started#SchemaValidation) libraries; Zod is used here for clarity.
  </AlertDescription>
</Alert>

```tsx showLineNumbers title="form.tsx"
import * as z from "zod"

const formSchema = z.object({
  title: z
    .string()
    .min(5, "Bug title must be at least 5 characters.")
    .max(32, "Bug title must be at most 32 characters."),
  description: z
    .string()
    .min(20, "Description must be at least 20 characters.")
    .max(100, "Description must be at most 100 characters."),
})
```

### Setup [#setup]

Create the form with `useForm` from React Hook Form and pass your schema to the `resolver` option.

```tsx showLineNumbers title="form.tsx" {10-16}
import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";
import * as z from "zod";

const formSchema = z.object({
  // ...
});

export const BugReportForm = () => {
  const form = useForm({
    resolver: zodResolver(formSchema),
    defaultValues: {
      title: "",
      description: "",
    },
  });

  const onSubmit = (data: z.infer<typeof formSchema>) => {
    console.log(data);
  }

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      {/* Build the form here */}
    </form>
  );
};
```

### Build [#build]

Build the form using the `Controller` from React Hook Form and the Shark `Field`.

<ComponentSource src="../examples/form/rhf/example-demo.tsx" />

### Done [#done]

That's it. You now have a fully accessible form with client-side validation.

When you submit the form, the `onSubmit` function will be called with the validated form data. If the form is invalid, React Hook Form will display the errors on `field.state.error` for `FieldError`.

## Validation [#validation]

### Client-side [#client-side]

React Hook Form validates your form data using the Zod schema. Define a schema and pass it to the `resolver` option of the `useForm` hook.

```tsx showLineNumbers title="example-form.tsx" {5-8,12}
import { zodResolver } from "@hookform/resolvers/zod"
import { useForm } from "react-hook-form"
import * as z from "zod"

const formSchema = z.object({
  title: z.string(),
  description: z.string().optional(),
})

export const ExampleForm = () => {
  const form = useForm({
    resolver: zodResolver(formSchema),
    defaultValues: {
      title: "",
      description: "",
    },
  })
}
```

### Modes [#modes]

Configure when validation runs via the `mode` option:

```tsx showLineNumbers title="form.tsx" {3}
const form = useForm({
  resolver: zodResolver(formSchema),
  mode: "onChange",
})
```

| Mode          | Description                                              |
| ------------- | -------------------------------------------------------- |
| `"onChange"`  | Validation triggers on every change.                     |
| `"onBlur"`    | Validation triggers on blur.                             |
| `"onSubmit"`  | Validation triggers on submit (default).                 |
| `"onTouched"` | Validation triggers on first blur, then on every change. |
| `"all"`       | Validation triggers on blur and change.                  |

## Displaying Errors [#displaying-errors]

Display errors next to the field using `FieldError`. For styling and accessibility:

* Add the `invalid` prop to the `Field` component.
* Don't need to add the `invalid` prop to the form control such as `Input`, `Checkbox`, etc.

```tsx showLineNumbers title="form.tsx" {5,8}
<Controller
  name="email"
  control={form.control}
  render={({ field, fieldState }) => (
    <Field invalid={fieldState.invalid}>
      <FieldLabel>Email</FieldLabel>
      <Input {...field} type="email" />
     <FieldError>{fieldState.error?.message}</FieldError>
    </Field>
  )}
/>
```

## Different types of fields [#different-types-of-fields]

### Input [#input]

* Spread the field object onto the `Input` component.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-input" showBorders="false" hasMaxHeight="false" />

### Textarea [#textarea]

* Spread the field object onto the `Textarea` component.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-textarea" showBorders="false" hasMaxHeight="false" />

### NativeSelect [#nativeselect]

* Spread the field object onto the `NativeSelect` component.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-native-select" showBorders="false" hasMaxHeight="false" />

### Select [#select]

* Wire `field.value` and `field.onChange` to `Select`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-select" showBorders="false" hasMaxHeight="false" />

### Checkbox [#checkbox]

* Wire `field.value` and `field.onChange` to `Checkbox`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.
* Remember to add `data-slot="checkbox-group"` to the `FieldGroup` component for proper styling and spacing.

<ComponentPreview componentName="form/rhf" fileName="example-checkbox" showBorders="false" hasMaxHeight="false" />

### Radio group [#radio-group]

* Wire `field.value` and `field.onChange` to `RadioGroup`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-radio-group" showBorders="false" hasMaxHeight="false" />

### Switch [#switch]

* Wire `field.value` and `field.onChange` to `Switch`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-switch" showBorders="false" hasMaxHeight="false" />

### NumberInput [#numberinput]

* Wire `field.value` and `field.onChange` to `NumberInput`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-number-input" showBorders="false" hasMaxHeight="false" />

### Slider [#slider]

* Wire `field.value` and `field.onChange` to `Slider`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-slider" showBorders="false" hasMaxHeight="false" />

### Combobox [#combobox]

* Wire `field.value` and `field.onChange` to `Combobox`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-combobox" showBorders="false" hasMaxHeight="false" />

### Autocomplete [#autocomplete]

* Wire `field.value` and `field.onChange` to `Autocomplete`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-autocomplete" showBorders="false" hasMaxHeight="false" />

### Date Picker [#date-picker]

* Wire `field.value` and `field.onChange` to `DatePicker`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-date-picker" showBorders="false" hasMaxHeight="false" />

### Input OTP [#input-otp]

* Wire `field.value` and `field.onChange` to `InputOTP`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-input-otp" showBorders="false" hasMaxHeight="false" />

### Rating [#rating]

* Wire `field.value` and `field.onChange` to `Rating`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-rating" showBorders="false" hasMaxHeight="false" />

### File Upload [#file-upload]

* Wire `field.value` and `field.onChange` to `FileUpload`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/rhf" fileName="example-file-upload" showBorders="false" hasMaxHeight="false" />

### Complex Forms [#complex-forms]

Here is an example of a more complex form with multiple fields and validation.

<ComponentPreview componentName="form/rhf" fileName="example-complex" showBorders="false" hasMaxHeight="false" />

## Resetting the Form [#resetting-the-form]

Use `form.reset()` to reset the form to its default values.

```tsx showLineNumbers
<Button type="button" variant="outline" onClick={() => form.reset()}>
  Reset
</Button>
```

## Array Fields [#array-fields]

React Hook Form provides a `useFieldArray` hook for managing dynamic array fields. This is useful when you need to add or remove fields dynamically.

<ComponentPreview componentName="form/rhf" fileName="example-array-emails" showBorders="false" hasMaxHeight="false" />

### Using useFieldArray [#using-usefieldarray]

Use the `useFieldArray` hook to manage array fields. It provides `fields`, `append`, and `remove` methods.

```tsx showLineNumbers title="form.tsx" {8-11}
import { useFieldArray, useForm } from "react-hook-form";

export const ExampleForm = () => {
  const form = useForm({
    // ... form config
  });

  const { fields, append, remove } = useFieldArray({
    control: form.control,
    name: "emails",
  });
}
```

### Array Field Structure [#array-field-structure]

Wrap your array fields in a `FieldSet` with a `FieldLegend` and `FieldDescription`.

```tsx showLineNumbers title="form.tsx"
<FieldSet className="gap-4">
  <FieldLegend variant="label">Email Addresses</FieldLegend>
  <FieldDescription>
    Add up to 5 email addresses where we can contact you.
  </FieldDescription>
  <FieldGroup className="gap-4">{/* Array items go here */}</FieldGroup>
</FieldSet>
```

### Controller Pattern for Array Items [#controller-pattern-for-array-items]

Map over the `fields` array and use `Controller` for each item. **Make sure to use `field.id` as the key**.

```tsx showLineNumbers title="form.tsx"
{
  fields.map((field, index) => (
    <Controller
      key={field.id}
      name={`emails.${index}.address`}
      control={form.control}
      render={({ field: controllerField, fieldState }) => (
        <Field invalid={fieldState.invalid} orientation="horizontal">
          <FieldContent>
            <InputGroup>
              <InputGroupInput
                {...controllerField}
                id={`form-rhf-array-email-${index}`}
                aria-invalid={fieldState.invalid}
                placeholder="name@example.com"
                type="email"
                autoComplete="email"
              />
              {/* Remove button */}
            </InputGroup>
            <FieldError>{fieldState.error?.message}</FieldError>
          </FieldContent>
        </Field>
      )}
    />
  ))}
```

### Adding Items [#adding-items]

Use the `append` method to add new items to the array.

```tsx showLineNumbers title="form.tsx"
<Button
  type="button"
  variant="outline"
  size="sm"
  onClick={() => append({ address: "" })}
  disabled={fields.length >= 5}
>
  Add Email Address
</Button>
```

### Removing Items [#removing-items]

Use the `remove` method to remove items from the array. Add the remove button conditionally.

```tsx showLineNumbers title="form.tsx"
{
  fields.length > 1 && (
    <InputGroupAddon align="inline-end">
      <InputGroupButton
        type="button"
        variant="ghost"
        size="icon-xs"
        onClick={() => remove(index)}
        aria-label={`Remove email ${index + 1}`}
      >
        <XIcon />
      </InputGroupButton>
    </InputGroupAddon>
  )}
}
```

### Array Validation [#array-validation]

Use Zod's `array` method to validate array fields.

```tsx showLineNumbers title="form.tsx"
const formSchema = z.object({
  emails: z
    .array(
      z.object({
        address: z.string().email("Enter a valid email address."),
      })
    )
    .min(1, "Add at least one email address.")
    .max(5, "You can add up to 5 email addresses."),
});
```


# TanStack Form (/docs/forms/tanstack-form)



This guide will cover building forms using the [Field](/docs/components/field) component, adding schema validation with [Zod](https://zod.dev), handling errors, ensuring accessibility, and more.

## Demo [#demo]

We’ll build a form with a text input and textarea. When you submit, the form data is validated and any errors will be shown.

<Alert>
  <InfoIcon />

  <AlertTitle>
    Browser validation disabled
  </AlertTitle>

  <AlertDescription>
    For the purposes of this demo, browser validation is disabled to illustrate schema validation. In production, keep native validation enabled when appropriate.
  </AlertDescription>
</Alert>

<ComponentPreview componentName="form/tanstack" fileName="example-demo" showBorders="false" hasMaxHeight="false" />

## Approach [#approach]

This form uses TanStack Form for state and Zod for validation. We'll build forms using the `Field` component, which gives you complete flexibility over the markup and styling.

* Uses TanStack Form's `useForm` hook for form state management.
* Uses `form.Field` with a render function for controlled inputs.
* Uses the `Field` components for building accessible forms.
* Uses client-side validation by passing your Zod schema into `validators`.

## Anatomy [#anatomy]

Here's a basic example of a form using TanStack Form with the `Field` component.

```tsx showLineNumbers {11-29}
<form
  onSubmit={(e) => {
    e.preventDefault()
    form.handleSubmit()
  }}
>
  <FieldGroup>
    <form.Field
      name="title"
      children={(field) => (
          <Field invalid={!field.state.meta.isValid}>
            <FieldLabel>Bug Title</FieldLabel>
            <Input
              name={field.name}
              value={field.state.value}
              onBlur={field.handleBlur}
              onChange={(e) => field.handleChange(e.target.value)}
              placeholder="Login button not working on mobile"
              autoComplete="off"
            />
            <FieldDescription>
              Provide a concise title for your bug report.
            </FieldDescription>
            <FieldError>
              {field.state.meta.errors
                .map((e) => e?.message || e)
                .join(", ")}
            </FieldError>
          </Field>
        )}
    />
  </FieldGroup>
  <Button type="submit">Submit</Button>
</form>
```

## Form [#form]

### Create a schema [#create-a-schema]

Define your form shape with a Zod schema.

<Alert>
  <InfoIcon />

  <AlertDescription>
    **Note:** TanStack Form works with Zod and other [Standard Schema](https://tanstack.com/form/latest/docs/framework/react/guides/validation#schema-validation) libraries via its validators API.
  </AlertDescription>
</Alert>

```tsx showLineNumbers title="form.tsx"
import * as z from "zod"

const formSchema = z.object({
  title: z
    .string()
    .min(5, "Bug title must be at least 5 characters.")
    .max(32, "Bug title must be at most 32 characters."),
  description: z
    .string()
    .min(20, "Description must be at least 20 characters.")
    .max(100, "Description must be at most 100 characters."),
})
```

### Setup [#setup]

* Create the form with `useForm` from TanStack Form and pass your schema to the `onSubmit` option.
* Use e.preventDefault() and e.stopPropagation() before calling form.handleSubmit()

```tsx showLineNumbers title="form.tsx" {9-18}
import { useForm } from "@tanstack/react-form";
import * as z from "zod";

const formSchema = z.object({
  // ...
});

export const ExampleForm = () => {
  const form = useForm({
    defaultValues: {
      title: "",
      description: "",
    },
    validators: { onSubmit: formSchema },
    onSubmit: async ({ value }) => {
      console.log(value);
    },
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        e.stopPropagation()
        form.handleSubmit();
      }}
    >
      {/* Build the form here */}
    </form>
  );
};
```

### Build [#build]

build the form using the `form.Field` from TanStack Form and the Shark `Field`.

<ComponentSource src="../examples/form/tanstack/example-demo.tsx" />

### Done [#done]

That's it. You now have a fully accessible form with client-side validation.

When you submit the form, the `onSubmit` handler receives validated values. If the form is invalid, TanStack Form exposes errors on `field.state.meta.errors` for `FieldError`.

## Validation [#validation]

### Client-side [#client-side]

TanStack Form validates your form data using the Zod schema. Define a schema and pass it to the `validators` option of the `useForm` hook.

```tsx showLineNumbers title="example-form.tsx" {4-7,15}
import { useForm } from "@tanstack/react-form"
import * as z from "zod"

const formSchema = z.object({
  title: z.string(),
  description: z.string().optional(),
})

export const ExampleForm = () => {
  const form = useForm({
    defaultValues: {
      title: "",
      description: "",
    },
    validators: { onSubmit: formSchema },
    onSubmit: async () => {},
  })
}
```

### Modes [#modes]

Configure when validation runs via the `validators` option:

```tsx showLineNumbers title="form.tsx" {2}
const form = useForm({
  validators: { onSubmit: formSchema },
})
```

| Mode         | Description                          |
| ------------ | ------------------------------------ |
| `"onChange"` | Validation triggers on every change. |
| `"onBlur"`   | Validation triggers on blur.         |
| `"onSubmit"` | Validation triggers on submit.       |

## Displaying Errors [#displaying-errors]

Display errors next to the field using `FieldError`. For styling and accessibility:

* Add the `invalid` prop to the `Field` component.
* Don't need to add the `invalid` prop to the form control such as `Input`, `Checkbox`, etc.

```tsx showLineNumbers title="form.tsx" {4,13-15}
<form.Field
  name="email"
  children={(field) => (
    <Field invalid={!field.state.meta.isValid}>
      <FieldLabel>Email</FieldLabel>
      <Input
        name={field.name}
        onBlur={field.handleBlur}
        onChange={(e) => field.handleChange(e.target.value)}
        type="email"
        value={field.state.value}
      />
      <FieldError>
        {field.state.meta.errors.map((e) => e?.message).join(", ")}
      </FieldError>
    </Field>
  )}
/>
```

## Different types of fields [#different-types-of-fields]

### Input [#input]

* Bind `field.state.value` and `field.handleChange` to `Input`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-input" showBorders="false" hasMaxHeight="false" />

### Textarea [#textarea]

* Bind `field.state.value` and `field.handleChange` to `Textarea`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-textarea" showBorders="false" hasMaxHeight="false" />

### NativeSelect [#nativeselect]

* Bind `field.state.value` and `field.handleChange` to `NativeSelect`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-native-select" showBorders="false" hasMaxHeight="false" />

### Select [#select]

* Wire `value` and `onValueChange` on `Select`. For overlays, call `field.handleBlur()` from `onInteractOutside` when your example needs blur sync.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-select" showBorders="false" hasMaxHeight="false" />

### Checkbox [#checkbox]

* Wire `field.state.value` and `field.handleChange` to `Checkbox`.
* Add the `invalid` prop to the `Field` component and pass the error message to the `FieldError` component.
* For checkbox arrays, use `mode="array"` on the `form.Field` component and TanStack Form's array helpers.
* Remember to add `data-slot="checkbox-group"` to the `FieldGroup` component for proper styling and spacing.

<ComponentPreview componentName="form/tanstack" fileName="example-checkbox" showBorders="false" hasMaxHeight="false" />

### Radio group [#radio-group]

* Wire `field.state.value` and `field.handleChange` to `RadioGroup`.
* Add the `invalid` prop to the `Field` component and pass the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-radio-group" showBorders="false" hasMaxHeight="false" />

### Switch [#switch]

* Use `field.state.value` and `field.handleChange` with `Switch`.
* Add the `invalid` prop to the `Field` component and pass the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-switch" showBorders="false" hasMaxHeight="false" />

### NumberInput [#numberinput]

* Wire `field.state.value` and `field.handleChange` to `NumberInput`.
* Add the `invalid` prop to the `Field` component and pass the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-number-input" showBorders="false" hasMaxHeight="false" />

### Slider [#slider]

* Wire `field.state.value` and `field.handleChange` to `Slider`.
* Add the `invalid` prop to the `Field` component and pass the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-slider" showBorders="false" hasMaxHeight="false" />

### Combobox [#combobox]

* Wire `field.state.value` and `field.handleChange` to `Combobox`.
* Add the `invalid` prop to the `Field` component and pass the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-combobox" showBorders="false" hasMaxHeight="false" />

### Autocomplete [#autocomplete]

* Wire `field.state.value` and `field.handleChange` to `Autocomplete`.
* Add the `invalid` prop to the `Field` component and pass the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-autocomplete" showBorders="false" hasMaxHeight="false" />

### Date Picker [#date-picker]

* Wire `field.state.value` and `field.handleChange` to `DatePicker`.
* Add the `invalid` prop to the `Field` component and pass the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-date-picker" showBorders="false" hasMaxHeight="false" />

### Input OTP [#input-otp]

* Use `field.state.value` (as `string[]`) and `field.handleChange` with `InputOTP`.
* Add the `invalid` prop to the `Field` component and pass the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-input-otp" showBorders="false" hasMaxHeight="false" />

### Rating [#rating]

* Wire `field.state.value` and `field.handleChange` to `Rating`.
* Add the `invalid` prop to the `Field` component and pass the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-rating" showBorders="false" hasMaxHeight="false" />

### File Upload [#file-upload]

* Wire `onFileAccept` to sync files into form state.
* Add the `invalid` prop to the `Field` component and pass the `FieldError` component.

<ComponentPreview componentName="form/tanstack" fileName="example-file-upload" showBorders="false" hasMaxHeight="false" />

### Complex Forms [#complex-forms]

Here is an example of a more complex form with multiple fields and validation.

<ComponentPreview componentName="form/tanstack" fileName="example-complex" showBorders="false" hasMaxHeight="false" />

## Resetting the Form [#resetting-the-form]

Use `form.reset()` to reset the form to its default values.

```tsx showLineNumbers
<Button type="button" variant="outline" onClick={() => form.reset()}>
  Reset
</Button>
```

## Array Fields [#array-fields]

TanStack Form provides powerful array field management with `mode="array"`. This allows you to dynamically add, remove, and update array items with full validation support.

<ComponentPreview componentName="form/tanstack" fileName="example-array-emails" showBorders="false" hasMaxHeight="false" />

### Array Field Structure [#array-field-structure]

Use `mode="array"` on the parent field to enable array field management.

```tsx showLineNumbers title="form.tsx" {3,11-13}
<form.Field
  name="emails"
  mode="array"
  children={(field) => (
    <FieldSet>
      <FieldLegend variant="label">Email Addresses</FieldLegend>
      <FieldDescription>
        Add up to 5 email addresses where we can contact you.
      </FieldDescription>
      <FieldGroup>
        {field.state.value.map((_, index) => (
          // Nested field for each array item
        ))}
      </FieldGroup>
    </FieldSet>
  )}
/>
```

### Nested Fields [#nested-fields]

Access individual array items using bracket notation: `fieldName[index].propertyName`.

```tsx showLineNumbers title="form.tsx"
<form.Field
  name={`emails[${index}].address`}
  children={(subField) => (
    <Field orientation="horizontal" invalid={!subField.state.meta.isValid}>
      <FieldContent>
        <InputGroup>
          <InputGroupInput
            name={subField.name}
            value={subField.state.value}
            onBlur={subField.handleBlur}
            onChange={(e) => subField.handleChange(e.target.value)}
            placeholder="name@example.com"
            type="email"
          />
          {field.state.value.length > 1 && (
            <InputGroupAddon align="inline-end">
              <InputGroupButton
                type="button"
                variant="ghost"
                size="icon-xs"
                onClick={() => field.removeValue(index)}
                aria-label={`Remove email ${index + 1}`}
              >
                <XIcon />
              </InputGroupButton>
            </InputGroupAddon>
          )}
        </InputGroup>
        <FieldError>
          {subField.state.meta.errors.map((e) => e?.message).join(", ")}
        </FieldError>
      </FieldContent>
    </Field>
  )}
/>
```

### Adding Items [#adding-items]

Use `field.pushValue(item)` to add items to an array field. You can disable the button when the array reaches its maximum length.

```tsx showLineNumbers title="form.tsx"
<Button
  type="button"
  variant="outline"
  size="sm"
  onClick={() => field.pushValue({ address: "" })}
  disabled={field.state.value.length >= 5}
>
  Add Email Address
</Button>
```

### Removing Items [#removing-items]

Use `field.removeValue(index)` to remove items from an array field. You can conditionally show the remove button only when there's more than one item.

```tsx showLineNumbers title="form.tsx"
{
  field.state.value.length > 1 && (
    <InputGroupButton
      onClick={() => field.removeValue(index)}
      aria-label={`Remove email ${index + 1}`}
    >
      <XIcon />
    </InputGroupButton>
  )
}
```

### Removing items [#removing-items-1]

Use `removeValue(index)` on the array field.

```tsx showLineNumbers title="form.tsx"
{
  emailsField.state.value.length > 1 && (
    <InputGroupAddon align="inline-end">
      <InputGroupButton
        type="button"
        variant="ghost"
        size="icon-xs"
        onClick={() => emailsField.removeValue(index)}
        aria-label={`Remove email ${index + 1}`}
      >
        <XIcon />
      </InputGroupButton>
    </InputGroupAddon>
  );
}
```

### Array validation [#array-validation]

Validate arrays with Zod’s `z.array()` and `.min()` / `.max()`.

```tsx showLineNumbers title="form.tsx"
const formSchema = z.object({
  emails: z
    .array(
      z.object({
        address: z.string().email("Enter a valid email address."),
      })
    )
    .min(1, "Add at least one email address.")
    .max(5, "You can add up to 5 email addresses."),
});
```


# useIsMobile (/docs/hooks/use-is-mobile)



`useIsMobile` tells you if the viewport is less than **768px**. It uses `matchMedia`, so it reacts instantly to browser zoom and device rotation, not just window resizing.

## Installation [#installation]

<CodeTabs>
  <TabsList defaultValue="cli">
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/use-is-mobile
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        This hook has no package dependencies beyond React.
      </Step>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="hooks/use-is-mobile.tsx" src="../hooks/use-is-mobile.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { useIsMobile } from "@/registry/react/hooks/use-is-mobile";
```

## Example [#example]

```tsx showLineNumbers
"use client";

import { useIsMobile } from "@/registry/react/hooks/use-is-mobile";

export function Example() {
  const isMobile = useIsMobile();

  return (
    <p className="text-muted-foreground text-sm">
      {isMobile ? "Mobile layout" : "Desktop layout"}
    </p>
  );
}
```


# Astro (/docs/installation/astro)





<div className="mt-6 grid gap-4 sm:grid-cols-3 sm:gap-6">
  <a href="#use-the-shark-preset">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the Shark preset" description="Initialize an Astro project with the Shark registry preset." />
    </Card>
  </a>

  <a href="#use-the-cli">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the CLI" description="Scaffold a new Astro project directly from the terminal." />
    </Card>
  </a>

  <a href="#existing-project">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Existing Project" description="Configure Shark UI manually in an existing Astro project." />
    </Card>
  </a>
</div>

## Use the Shark Preset [#use-the-shark-preset]

<Steps>
  ### Create Project [#create-project]

  Run the `init` command with the Shark preset and the Astro template:

  ```bash
  npx shadcn@latest init @shark/style -t astro
  ```

  ### Add Components [#add-components]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components in an Astro page with a React client directive:

  ```astro title="src/pages/index.astro" showLineNumbers
  ---
  import Layout from "@/layouts/main.astro";
  import { Button } from "@/components/ui/button";
  ---

  <Layout>
    <div class="grid h-screen place-items-center content-center">
      <Button client:load>Button</Button>
    </div>
  </Layout>
  ```
</Steps>

<div id="use-the-cli" className="scroll-mt-24" />

## Use the CLI [#use-the-cli]

<Steps>
  ### Create Project [#create-project-1]

  Run the `init` command to scaffold a new Astro project and configure Shark UI:

  ```bash
  npx shadcn@latest init @shark/style -t astro
  ```

  For a monorepo project, use the `--monorepo` flag:

  ```bash
  npx shadcn@latest init @shark/style -t astro --monorepo
  ```

  ### Add Components [#add-components-1]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  If you created a monorepo, run the command from `apps/web` or specify the workspace from the repo root:

  ```bash
  npx shadcn@latest add @shark/button -c apps/web
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components in an Astro page with a React client directive:

  ```astro title="src/pages/index.astro" showLineNumbers
  ---
  import Layout from "@/layouts/main.astro";
  import { Button } from "@/components/ui/button";
  ---

  <Layout>
    <div class="grid h-screen place-items-center content-center">
      <Button client:load>Button</Button>
    </div>
  </Layout>
  ```

  If you created a monorepo, update `apps/web/src/pages/index.astro` and import from your workspace UI package instead. The monorepo layout at `apps/web/src/layouts/main.astro` already imports your shared global CSS for you.
</Steps>

<div id="existing-project" className="scroll-mt-24" />

## Existing Project [#existing-project]

<Steps>
  ### Create Project [#create-project-2]

  If you need a new Astro project, create one first. Otherwise, skip this step.

  ```bash
  npm create astro@latest astro-app -- --template with-tailwindcss --install --add react --git
  ```

  This command sets up Tailwind CSS and the React integration for you. If you're adding Shark UI to an older or custom Astro app, make sure both are configured before continuing.

  The Tailwind starter loads your global stylesheet through `src/layouts/main.astro`. Keep that layout in place, or make sure your page imports `@/styles/global.css`.

  ### Edit tsconfig.json [#edit-tsconfigjson]

  Add path aliases so imports resolve correctly:

  ```ts title="tsconfig.json" showLineNumbers
  {
    "compilerOptions": {
      "baseUrl": ".",
      "paths": {
        "@/*": ["./src/*"]
      }
    }
  }
  ```

  ### Run the CLI [#run-the-cli]

  Run the `shadcn` init command with the Shark preset to set up your project.

  ```bash
  npx shadcn@latest init @shark/style
  ```

  ### Add Components [#add-components-2]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components in an Astro page with a React client directive:

  ```astro title="src/pages/index.astro" showLineNumbers
  ---
  import Layout from "@/layouts/main.astro";
  import { Button } from "@/components/ui/button";
  ---

  <Layout>
    <div class="grid h-screen place-items-center content-center">
      <Button client:load>Button</Button>
    </div>
  </Layout>
  ```
</Steps>


# Laravel (/docs/installation/laravel)





The shadcn CLI does not scaffold a new Laravel app. Start by creating a Laravel app with the React starter kit, then choose how you want to configure Shark UI.

### Create Project [#create-project]

Create a new Laravel app using the Laravel installer:

```bash
laravel new my-app
```

If you already have a Laravel app with React and Inertia configured, skip this step.

Choose the **React** starter kit when prompted. For more information, see the official [Laravel frontend documentation](https://laravel.com/docs/starter-kits#react).

Then move into your project directory:

```bash
cd my-app
```

<div className="mt-6 grid gap-4 sm:grid-cols-2 sm:gap-6">
  <a href="#use-the-shark-preset">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the Shark preset" description="Initialize Shark UI in your Laravel app with the registry preset." />
    </Card>
  </a>

  <a href="#use-the-cli">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the CLI" description="Configure Shark UI in your Laravel app directly from the terminal." />
    </Card>
  </a>
</div>

## Use the Shark Preset [#use-the-shark-preset]

<Steps>
  ### Run the Command [#run-the-command]

  Run the `init` command with the Shark preset and the Laravel template from the root of your Laravel app:

  ```bash
  npx shadcn@latest init @shark/style -t laravel
  ```

  When asked to overwrite `components.json` and components, choose `Yes`.

  ### Add Components [#add-components]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Switch` component to your project:

  ```bash
  npx shadcn@latest add @shark/switch
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="resources/js/pages/index.tsx" showLineNumbers
  import { Switch } from "@/components/ui/switch";

  const MyPage = () => {
    return (
      <div>
        <Switch />
      </div>
    );
  };

  export default MyPage;
  ```
</Steps>

<div id="use-the-cli" className="scroll-mt-24" />

## Use the CLI [#use-the-cli]

<Steps>
  ### Run the CLI [#run-the-cli]

  Run the `shadcn` init command with the Shark preset from the root of your Laravel app:

  ```bash
  npx shadcn@latest init @shark/style
  ```

  When asked to overwrite `components.json` and components, choose `Yes`.

  ### Add Components [#add-components-1]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Switch` component to your project:

  ```bash
  npx shadcn@latest add @shark/switch
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="resources/js/pages/index.tsx" showLineNumbers
  import { Switch } from "@/components/ui/switch";

  const MyPage = () => {
    return (
      <div>
        <Switch />
      </div>
    );
  };

  export default MyPage;
  ```
</Steps>


# Manual Installation (/docs/installation/manual)



Manual setup gives you full control over every file. Use this when the CLI does not fit your setup or you prefer to wire the project yourself.

### Add Tailwind CSS [#add-tailwind-css]

Components are styled using Tailwind CSS. Install Tailwind CSS in your project first:

[Follow the Tailwind CSS installation instructions.](https://tailwindcss.com/docs/installation)

### Add dependencies [#add-dependencies]

Add the dependencies used by Shark UI components:

```bash
pnpm add @ark-ui/react tailwind-variants clsx tailwind-merge lucide-react tw-animate-css
```

### Configure import aliases [#configure-import-aliases]

Choose one of the following alias setups.

#### Option A: tsconfig.json paths [#option-a-tsconfigjson-paths]

```json title="tsconfig.json" showLineNumbers {2-6}
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}
```

#### Option B: package.json#imports [#option-b-packagejsonimports]

```json title="package.json" showLineNumbers
{
  "imports": {
    "#components/*": "./src/components/*.tsx",
    "#lib/*": "./src/lib/*.ts",
    "#hooks/*": "./src/hooks/*.ts"
  }
}
```

```json title="tsconfig.json" showLineNumbers
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "resolvePackageJsonImports": true
  }
}
```

The `@` alias is a preference. You can use other aliases if needed. If you use `package.json#imports`, keep the matching alias roots in `components.json`.

### Configure styles [#configure-styles]

Create a file `styles/globals.css` and follow [Styling](/docs/styling#css-configuration) to configure the theme.

### Add a cn helper [#add-a-cn-helper]

```ts title="lib/utils.ts" showLineNumbers
import { type ClassValue, clsx } from "clsx"
import { twMerge } from "tailwind-merge"

export const cn = (...inputs: ClassValue[]) => twMerge(clsx(inputs))
```

### Create a components.json file [#create-a-componentsjson-file]

Create a `components.json` file in the project root so the shadcn CLI knows where to write components if you use it later.

```json title="components.json" showLineNumbers
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "styles/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide",
  "registries": {
    "@shark": "https://shark.vini.one/r/{name}.json"
  }
}
```

If you're using `package.json#imports`, use the corresponding `#...` aliases instead:

```json title="components.json" showLineNumbers
{
  "aliases": {
    "components": "#components",
    "utils": "#lib/utils",
    "ui": "#components/ui",
    "lib": "#lib",
    "hooks": "#hooks"
  }
}
```

## Adding components [#adding-components]

You can add components with the CLI or copy them manually from the component docs:

* **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
* **Manual**: Copy component source from Manual tab in the component docs.

You can also install every component at once:

```bash
npx shadcn@latest add @shark/ui
```


# Next.js (/docs/installation/next)





<div className="mt-6 grid gap-4 sm:grid-cols-3 sm:gap-6">
  <a href="#use-the-shark-preset">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the Shark preset" description="Initialize a Next.js project with the Shark registry preset." />
    </Card>
  </a>

  <a href="#use-the-cli">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the CLI" description="Scaffold a new Next.js project directly from the terminal." />
    </Card>
  </a>

  <a href="#existing-next-project">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Existing Project" description="Configure Shark UI manually in an existing Next.js project." />
    </Card>
  </a>
</div>

## Use the Shark Preset [#use-the-shark-preset]

<Steps>
  ### Create Project [#create-project]

  Run the `init` command with the Shark preset and the Next.js template:

  ```bash
  npx shadcn@latest init @shark/style -t next
  ```

  ### Add Components [#add-components]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="app/page.tsx" showLineNumbers
  import { Button } from "@/components/ui/button";

  export default function Home() {
    return (
      <div className="flex min-h-svh items-center justify-center">
        <Button>Click me</Button>
      </div>
    );
  }
  ```
</Steps>

<div id="use-the-cli" className="scroll-mt-24" />

## Use the CLI [#use-the-cli]

<Steps>
  ### Create Project [#create-project-1]

  Run the `init` command to scaffold a new Next.js project and configure Shark UI:

  ```bash
  npx shadcn@latest init @shark/style -t next
  ```

  ### Add Components [#add-components-1]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="app/page.tsx" showLineNumbers
  import { Button } from "@/components/ui/button";

  export default function Home() {
    return (
      <div className="flex min-h-svh items-center justify-center">
        <Button>Click me</Button>
      </div>
    );
  }
  ```
</Steps>

<div id="existing-next-project" className="scroll-mt-24" />

## Existing Project [#existing-project]

<Steps>
  ### Create Project [#create-project-2]

  If you need a new Next.js project, create one with `create-next-app`. Otherwise, skip this step.

  ```bash
  npx create-next-app@latest
  ```

  Choose the recommended defaults so Tailwind CSS, the App Router, and the default `@/*` import alias are configured for you.

  If you prefer a `src/` directory, use `--src-dir` or choose `Yes` when prompted:

  ```bash
  npx create-next-app@latest --src-dir
  ```

  With `--src-dir`, Next.js places your app in `src/app` and configures the `@/*` alias to point to `./src/*`.

  ### Configure Tailwind CSS and Import Aliases [#configure-tailwind-css-and-import-aliases]

  If you created your project with the recommended `create-next-app` defaults, you can skip this step.

  If you're adding Shark UI to an older or custom Next.js app, make sure Tailwind CSS is installed first. You can follow the official [Next.js installation guide](https://nextjs.org/docs/app/getting-started).

  Then make sure your `tsconfig.json` includes the `@/*` import alias:

  ```json title="tsconfig.json" showLineNumbers
  {
    "compilerOptions": {
      "paths": {
        "@/*": ["./*"]
      }
    }
  }
  ```

  If you used `--src-dir`, point the alias to `./src/*` instead.

  ### Run the CLI [#run-the-cli]

  Run the `shadcn` init command with the Shark preset to set up your project.

  ```bash
  npx shadcn@latest init @shark/style
  ```

  ### Add Components [#add-components-2]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="app/page.tsx" showLineNumbers
  import { Button } from "@/components/ui/button";

  export default function Home() {
    return (
      <div className="flex min-h-svh items-center justify-center">
        <Button>Click me</Button>
      </div>
    );
  }
  ```

  If you used `--src-dir`, add the component to `src/app/page.tsx` instead.
</Steps>


# React Router (/docs/installation/react-router)





<div className="mt-6 grid gap-4 sm:grid-cols-3 sm:gap-6">
  <a href="#use-the-shark-preset">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the Shark preset" description="Initialize a React Router project with the Shark registry preset." />
    </Card>
  </a>

  <a href="#use-the-cli">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the CLI" description="Scaffold a new React Router project directly from the terminal." />
    </Card>
  </a>

  <a href="#existing-project">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Existing Project" description="Configure Shark UI manually in an existing React Router project." />
    </Card>
  </a>
</div>

## Use the Shark Preset [#use-the-shark-preset]

<Steps>
  ### Create Project [#create-project]

  ```bash
  npx shadcn@latest init @shark/style -t react-router
  ```

  ### Add Components [#add-components]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="app/routes/home.tsx" showLineNumbers
  import { Button } from "~/components/ui/button";
  import type { Route } from "./+types/home";

  export const meta = ({}: Route.MetaArgs) => {
    return [
      { title: "New React Router App" },
      { name: "description", content: "Welcome to React Router!" },
    ];
  };

  export default function Home() {
    return (
      <div className="flex min-h-svh flex-col items-center justify-center">
        <Button>Click me</Button>
      </div>
    );
  }
  ```
</Steps>

<div id="use-the-cli" className="scroll-mt-24" />

## Use the CLI [#use-the-cli]

<Steps>
  ### Create Project [#create-project-1]

  Run the `init` command to scaffold a new React Router project and configure Shark UI:

  ```bash
  npx shadcn@latest init @shark/style -t react-router
  ```

  For a monorepo project, use the `--monorepo` flag:

  ```bash
  npx shadcn@latest init @shark/style -t react-router --monorepo
  ```

  ### Add Components [#add-components-1]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  If you created a monorepo, run the command from `apps/web` or specify the workspace from the repo root:

  ```bash
  npx shadcn@latest add @shark/button -c apps/web
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="app/routes/home.tsx" showLineNumbers
  import { Button } from "~/components/ui/button";
  import type { Route } from "./+types/home";

  export const meta = ({}: Route.MetaArgs) => {
    return [
      { title: "New React Router App" },
      { name: "description", content: "Welcome to React Router!" },
    ];
  };

  export default function Home() {
    return (
      <div className="flex min-h-svh flex-col items-center justify-center">
        <Button>Click me</Button>
      </div>
    );
  }
  ```

  If you created a monorepo, update `apps/web/app/routes/home.tsx` and import from your workspace UI package instead.
</Steps>

<div id="existing-project" className="scroll-mt-24" />

## Existing Project [#existing-project]

<Steps>
  ### Create Project [#create-project-2]

  If you need a new React Router project, create one first. Otherwise, skip this step.

  ```bash
  npx create-react-router@latest my-app
  ```

  ### Run the CLI [#run-the-cli]

  Run the `shadcn` init command with the Shark preset to set up your project.

  ```bash
  npx shadcn@latest init @shark/style
  ```

  ### Add Components [#add-components-2]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="app/routes/home.tsx" showLineNumbers
  import { Button } from "~/components/ui/button";
  import type { Route } from "./+types/home";

  export const meta = ({}: Route.MetaArgs) => {
    return [
      { title: "New React Router App" },
      { name: "description", content: "Welcome to React Router!" },
    ];
  };

  export default function Home() {
    return (
      <div className="flex min-h-svh flex-col items-center justify-center">
        <Button>Click me</Button>
      </div>
    );
  }
  ```
</Steps>


# TanStack Start (/docs/installation/tanstack-start)





<div className="mt-6 grid gap-4 sm:grid-cols-3 sm:gap-6">
  <a href="#use-the-shark-preset">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the Shark preset" description="Initialize a TanStack Start project with the Shark registry preset." />
    </Card>
  </a>

  <a href="#use-the-cli">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the CLI" description="Scaffold a new TanStack Start project from the terminal." />
    </Card>
  </a>

  <a href="#existing-project">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Existing Project" description="Configure Shark UI manually in an existing TanStack Start project." />
    </Card>
  </a>
</div>

## Use the Shark Preset [#use-the-shark-preset]

<Steps>
  ### Create Project [#create-project]

  Run the `init` command with the Shark preset and the TanStack Start template:

  ```bash
  npx shadcn@latest init @shark/style -t start
  ```

  ### Add Components [#add-components]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="src/routes/index.tsx" showLineNumbers
  import { createFileRoute } from "@tanstack/react-router";
  import { Button } from "@/components/ui/button";

  export const Route = createFileRoute("/")({
    component: App,
  });

  function App() {
    return (
      <div className="flex min-h-svh items-center justify-center p-6">
        <Button>Click me</Button>
      </div>
    );
  }
  ```
</Steps>

<div id="use-the-cli" className="scroll-mt-24" />

## Use the CLI [#use-the-cli]

<Steps>
  ### Create Project [#create-project-1]

  Run the `init` command to scaffold a new TanStack Start project and configure Shark UI:

  ```bash
  npx shadcn@latest init @shark/style -t start
  ```

  For a monorepo project, use the `--monorepo` flag:

  ```bash
  npx shadcn@latest init @shark/style -t start --monorepo
  ```

  ### Add Components [#add-components-1]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  If you created a monorepo, run the command from `apps/web` or specify the workspace from the repo root:

  ```bash
  npx shadcn@latest add @shark/button -c apps/web
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="src/routes/index.tsx" showLineNumbers
  import { createFileRoute } from "@tanstack/react-router";
  import { Button } from "@/components/ui/button";

  export const Route = createFileRoute("/")({
    component: App,
  });

  function App() {
    return (
      <div className="flex min-h-svh items-center justify-center p-6">
        <Button>Click me</Button>
      </div>
    );
  }
  ```

  If you created a monorepo, update `apps/web/src/routes/index.tsx` and import from your workspace UI package instead.
</Steps>

<div id="existing-project" className="scroll-mt-24" />

## Existing Project [#existing-project]

<Steps>
  ### Create Project [#create-project-2]

  If you need a new TanStack Start project, create one first. Otherwise, skip this step.

  ```bash
  npx @tanstack/cli@latest create
  ```

  Choose TanStack Start, the React framework, and the recommended defaults so Tailwind CSS and the `@/*` import alias are configured for you.

  Do not add the `shadcn` add-on when prompted. The `shadcn` CLI will configure Shark UI later in this guide.

  The TanStack CLI already configures Tailwind CSS and the default `@/*` import alias for you. If you're adding Shark UI to an older or custom TanStack Start app, make sure both are configured before continuing.

  ### Run the CLI [#run-the-cli]

  Run the `shadcn` init command with the Shark preset to set up your project.

  ```bash
  npx shadcn@latest init @shark/style
  ```

  ### Add Components [#add-components-2]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="src/routes/index.tsx" showLineNumbers
  import { createFileRoute } from "@tanstack/react-router";
  import { Button } from "@/components/ui/button";

  export const Route = createFileRoute("/")({
    component: App,
  });

  function App() {
    return (
      <div className="flex min-h-svh items-center justify-center p-6">
        <Button>Click me</Button>
      </div>
    );
  }
  ```
</Steps>


# Vite (/docs/installation/vite)





<div className="mt-6 grid gap-4 sm:grid-cols-3 sm:gap-6">
  <a href="#use-the-shark-preset">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the Shark preset" description="Initialize a Vite project with the Shark registry preset." />
    </Card>
  </a>

  <a href="#use-the-cli">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Use the CLI" description="Scaffold a new Vite project directly from the terminal." />
    </Card>
  </a>

  <a href="#existing-project">
    <Card className="h-full transition-colors hover:bg-muted">
      <CardHeader title="Existing Project" description="Configure Shark UI manually in an existing Vite project." />
    </Card>
  </a>
</div>

## Use the Shark Preset [#use-the-shark-preset]

<Steps>
  ### Create Project [#create-project]

  Run the `init` command with the Shark preset and the Vite template:

  ```bash
  npx shadcn@latest init @shark/style -t vite
  ```

  ### Add Components [#add-components]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="src/App.tsx" showLineNumbers
  import { Button } from "@/components/ui/button";

  function App() {
    return (
      <div className="flex min-h-svh flex-col items-center justify-center">
        <Button>Click me</Button>
      </div>
    );
  }

  export default App;
  ```
</Steps>

<div id="use-the-cli" className="scroll-mt-24" />

## Use the CLI [#use-the-cli]

<Steps>
  ### Create Project [#create-project-1]

  Run the `init` command to scaffold a new Vite project and configure Shark UI:

  ```bash
  npx shadcn@latest init @shark/style -t vite
  ```

  For a monorepo project, use the `--monorepo` flag:

  ```bash
  npx shadcn@latest init @shark/style -t vite --monorepo
  ```

  ### Add Components [#add-components-1]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  If you created a monorepo, run the command from `apps/web` or specify the workspace from the repo root:

  ```bash
  npx shadcn@latest add @shark/button -c apps/web
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="src/App.tsx" showLineNumbers
  import { Button } from "@/components/ui/button";

  function App() {
    return (
      <div className="flex min-h-svh flex-col items-center justify-center">
        <Button>Click me</Button>
      </div>
    );
  }

  export default App;
  ```

  If you created a monorepo, update `apps/web/src/App.tsx` and import from your workspace UI package instead.
</Steps>

<div id="existing-project" className="scroll-mt-24" />

## Existing Project [#existing-project]

<Steps>
  ### Create Project [#create-project-2]

  If you need a new Vite project, create one first and select the **React + TypeScript** template. Otherwise, skip this step.

  ```bash
  npm create vite@latest
  ```

  ### Add Tailwind CSS [#add-tailwind-css]

  If your project already has Tailwind CSS configured, skip this step.

  ```bash
  npm install tailwindcss @tailwindcss/vite
  ```

  Replace everything in `src/index.css` with the following:

  ```css title="src/index.css"
  @import "tailwindcss";
  ```

  ### Edit tsconfig.json [#edit-tsconfigjson]

  Vite splits TypeScript config across multiple files. Add `baseUrl` and `paths` to the `compilerOptions` in both `tsconfig.json` and `tsconfig.app.json`:

  ```ts title="tsconfig.json" showLineNumbers
  {
    "files": [],
    "references": [
      {
        "path": "./tsconfig.app.json"
      },
      {
        "path": "./tsconfig.node.json"
      }
    ],
    "compilerOptions": {
      "baseUrl": ".",
      "paths": {
        "@/*": ["./src/*"]
      }
    }
  }
  ```

  ### Edit tsconfig.app.json [#edit-tsconfigappjson]

  Add the same path resolution so your IDE resolves imports correctly:

  ```ts title="tsconfig.app.json" showLineNumbers
  {
    "compilerOptions": {
      "baseUrl": ".",
      "paths": {
        "@/*": ["./src/*"]
      }
    }
  }
  ```

  ### Update vite.config.ts [#update-viteconfigts]

  Add the path alias so Vite resolves `@/` at build time:

  ```bash
  npm install -D @types/node
  ```

  ```typescript title="vite.config.ts" showLineNumbers
  import path from "path"
  import tailwindcss from "@tailwindcss/vite"
  import react from "@vitejs/plugin-react"
  import { defineConfig } from "vite"

  export default defineConfig({
    plugins: [react(), tailwindcss()],
    resolve: {
      alias: {
        "@": path.resolve(__dirname, "./src"),
      },
    },
  })
  ```

  ### Run the CLI [#run-the-cli]

  Run the `shadcn` init command with the Shark preset to set up your project.

  ```bash
  npx shadcn@latest init @shark/style
  ```

  ### Add Components [#add-components-2]

  You can add components with the CLI or copy them manually from the component docs:

  * **CLI**: Run `npx shadcn@latest add @shark/<component>` (e.g. `button`, `dialog`).
  * **Manual**: Copy component source from Manual tab in the component docs.

  For example, add the `Button` component to your project:

  ```bash
  npx shadcn@latest add @shark/button
  ```

  You can also install every component at once:

  ```bash
  npx shadcn@latest add @shark/ui
  ```

  Then import and use components like this:

  ```tsx title="src/App.tsx" showLineNumbers
  import { Button } from "@/components/ui/button";

  function App() {
    return (
      <div className="flex min-h-svh flex-col items-center justify-center">
        <Button>Click me</Button>
      </div>
    );
  }

  export default App;
  ```
</Steps>


# Client Only (/docs/utilities/client-only)



<ComponentPreview componentName="client-only" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/client-only
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/client-only.tsx" src="/client-only.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { ClientOnly } from "@/registry/react/components/client-only";
```

```tsx
<ClientOnly>
  <div>This content only renders on the client.</div>
</ClientOnly>
```

## Examples [#examples]

### With fallback [#with-fallback]

Pass `fallback` to show content while the client-only content is loading:

<ComponentPreview componentName="client-only" fileName="example-fallback" />

## API Reference [#api-reference]

### ClientOnly [#clientonly]

Shows children only on the client. Useful for hydration-safe client components.

| Prop       | Type        | Default |
| ---------- | ----------- | ------- |
| `fallback` | `ReactNode` | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/utilities/client-only#api-reference).


# Download Trigger (/docs/utilities/download-trigger)



<ComponentPreview componentName="download-trigger" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/download-trigger
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/download-trigger.tsx" src="/download-trigger.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { DownloadTrigger } from "@/registry/react/components/download-trigger";
```

```tsx
<DownloadTrigger
  data="..."
  fileName="schema.json"
  mimeType="application/json"
>
  Download
</DownloadTrigger>
```

## Examples [#examples]

### Download SVG [#download-svg]

Download an SVG file by passing the SVG markup to `data` and setting `mimeType` to `image/svg+xml`.

<ComponentPreview componentName="download-trigger" fileName="example-download-svg" />

### Promise [#promise]

Trigger downloads from a promise that returns a `Blob`, `File`, or `string`. Pass a function to `data`.

<ComponentPreview componentName="download-trigger" fileName="example-promise" />

## API Reference [#api-reference]

### DownloadTrigger [#downloadtrigger]

| Prop       | Type                                                         | Default |
| ---------- | ------------------------------------------------------------ | ------- |
| `data`     | `DownloadableData \| (() => MaybePromise<DownloadableData>)` | -       |
| `fileName` | `string`                                                     | -       |
| `mimeType` | `FileMimeType`                                               | -       |
| `asChild`  | `boolean`                                                    | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/utilities/download-trigger#api-reference).


# Format (/docs/utilities/format)



<ComponentPreview componentName="format" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/format
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/format.tsx" src="/format.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { 
  FormatByte, 
  FormatNumber, 
  FormatRelativeTime 
} from "@/registry/react/components/format";
```

```tsx
<FormatByte value={120_000} />
<FormatNumber value={1234567} />
<FormatRelativeTime value={new Date("2025-05-05")} />
```

## Examples [#examples]

### Format Byte [#format-byte]

Format byte values as file sizes.

<ComponentPreview componentName="format" fileName="example-byte" />

#### Unit display [#unit-display]

Use the `unitDisplay` prop to control how the unit is displayed.

<ComponentPreview componentName="format" fileName="example-byte-unit-display" />

#### Unit system [#unit-system]

Use `unitSystem` to choose between decimal (1000 bytes) or binary (1024 bytes).

<ComponentPreview componentName="format" fileName="example-byte-unit-system" />

### Format Relative Time [#format-relative-time]

Format dates as relative time.

<ComponentPreview componentName="format" fileName="example-relative-time" />

#### Style [#style]

Use the `style` prop for long, short, or narrow format.

<ComponentPreview componentName="format" fileName="example-relative-time-short" />

### Format Number [#format-number]

Format numbers with locale-aware options.

<ComponentPreview componentName="format" fileName="example-number" />

#### Currency [#currency]

Use `style="currency"` with the `currency` prop for currency formatting.

<ComponentPreview componentName="format" fileName="example-number-currency" />

#### Percentage [#percentage]

Use `style="percent"` to format numbers as percentages.

<ComponentPreview componentName="format" fileName="example-number-percent" />

#### Compact notation [#compact-notation]

Use `notation="compact"` for compact display.

<ComponentPreview componentName="format" fileName="example-number-compact" />

## API Reference [#api-reference]

### FormatByte [#formatbyte]

| Prop          | Type                                | Default  |
| ------------- | ----------------------------------- | -------- |
| `value`       | `number`                            | -        |
| `unit`        | `"byte"` \| `"bit"`                 | `"byte"` |
| `unitDisplay` | `"long"` \| `"short"` \| `"narrow"` | -        |
| `unitSystem`  | `"decimal"` \| `"binary"`           | -        |
| `locale`      | `string`                            | -        |

### FormatRelativeTime [#formatrelativetime]

| Prop      | Type                                | Default |
| --------- | ----------------------------------- | ------- |
| `value`   | `Date` \| `number`                  | -       |
| `numeric` | `"always"` \| `"auto"`              | -       |
| `style`   | `"long"` \| `"short"` \| `"narrow"` | -       |
| `locale`  | `string`                            | -       |

### FormatNumber [#formatnumber]

| Prop                    | Type                                                             | Default      |
| ----------------------- | ---------------------------------------------------------------- | ------------ |
| `value`                 | `number`                                                         | -            |
| `locale`                | `string`                                                         | -            |
| `style`                 | `"decimal"` \| `"percent"` \| `"currency"` \| `"unit"`           | `"decimal"`  |
| `currency`              | `string`                                                         | -            |
| `unit`                  | `string`                                                         | -            |
| `notation`              | `"standard"` \| `"compact"` \| `"scientific"` \| `"engineering"` | `"standard"` |
| `minimumFractionDigits` | `number`                                                         | -            |
| `maximumFractionDigits` | `number`                                                         | -            |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/components/format#api-reference).


# Highlight (/docs/utilities/highlight)



<ComponentPreview componentName="highlight" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/highlight
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/highlight.tsx" src="/highlight.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Highlight } from "@/registry/react/components/highlight";
```

```tsx
<Highlight
  query="amet"
  text="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
/>
```

## Examples [#examples]

### Multiple [#multiple]

Pass an array of strings to the `query` prop to highlight multiple substrings.

<ComponentPreview componentName="highlight" fileName="example-multiple" />

### Search Query [#search-query]

Use the Highlight component to highlight search query results.

<ComponentPreview componentName="highlight" fileName="example-search-query" />

### With Squiggle [#with-squiggle]

Use a custom decoration like a wavy underline for a fancier highlight effect.

<ComponentPreview componentName="highlight" fileName="example-squiggle" />

### Custom Style [#custom-style]

Use the `className` prop to customize the style of the highlighted text.

<ComponentPreview componentName="highlight" fileName="example-custom-style" />

## API Reference [#api-reference]

### Highlight [#highlight]

| Prop         | Type                 | Default      |
| ------------ | -------------------- | ------------ |
| `query`      | `string \| string[]` | **required** |
| `text`       | `string`             | **required** |
| `ignoreCase` | `boolean`            | `false`      |
| `exactMatch` | `boolean`            | `false`      |
| `className`  | `string`             | `""`         |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/utilities/highlight#api-reference).


# Hitbox (/docs/utilities/hitbox)



<ComponentPreview componentName="hitbox" />

Kudos to [Kian Bazza](https://bazza.dev/craft/2026/hit-area) for the original implementation.

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/hitbox
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Import the following semantic color variables into your CSS file when using 

        `hitbox-debug`
      </Step>

      <CodeCollapsibleWrapper>
        ```css
        @theme inline {
          --color-info: var(--info);
          --color-success: var(--success);
        }

        :root {
          --info: var(--color-blue-500);
          --success: var(--color-emerald-500);
        }

        .dark {
          --info: var(--color-blue-500);
          --success: var(--color-emerald-500);
        }
        ```
      </CodeCollapsibleWrapper>

      <Step>
        Import the following CSS rules into your 

        `globals.css`
      </Step>

      ```css title="globals.css" showLineNumbers
      @utility hitbox-debug {
        position: relative;
        &::before {
          content: "";
          position: absolute;
          top: var(--hitbox-t, 0px);
          right: var(--hitbox-r, 0px);
          bottom: var(--hitbox-b, 0px);
          left: var(--hitbox-l, 0px);
          pointer-events: inherit;
          @apply border border-dashed border-info bg-info/10;
        }
        &:hover::before {
          @apply border border-dashed border-success bg-success/10;
        }
      }
      @utility hitbox {
        position: relative;
        &::before {
          content: "";
          position: absolute;
          top: var(--hitbox-t, 0px);
          right: var(--hitbox-r, 0px);
          bottom: var(--hitbox-b, 0px);
          left: var(--hitbox-l, 0px);
          pointer-events: inherit;
        }
      }
      @utility hitbox-* {
        position: relative;
        --hitbox-t: calc(-1 * --spacing(--value(number, [*])));
        --hitbox-b: calc(-1 * --spacing(--value(number, [*])));
        --hitbox-l: calc(-1 * --spacing(--value(number, [*])));
        --hitbox-r: calc(-1 * --spacing(--value(number, [*])));
        &::before {
          content: "";
          position: absolute;
          top: var(--hitbox-t, 0px);
          right: var(--hitbox-r, 0px);
          bottom: var(--hitbox-b, 0px);
          left: var(--hitbox-l, 0px);
          pointer-events: inherit;
        }
      }
      @utility hitbox-l-* {
        position: relative;
        --hitbox-l: calc(-1 * --spacing(--value(number, [*])));
        &::before { content: ""; position: absolute; top: var(--hitbox-t, 0px); right: var(--hitbox-r, 0px); bottom: var(--hitbox-b, 0px); left: var(--hitbox-l, 0px); pointer-events: inherit; }
      }
      @utility hitbox-r-* {
        position: relative;
        --hitbox-r: calc(-1 * --spacing(--value(number, [*])));
        &::before { content: ""; position: absolute; top: var(--hitbox-t, 0px); right: var(--hitbox-r, 0px); bottom: var(--hitbox-b, 0px); left: var(--hitbox-l, 0px); pointer-events: inherit; }
      }
      @utility hitbox-t-* {
        position: relative;
        --hitbox-t: calc(-1 * --spacing(--value(number, [*])));
        &::before { content: ""; position: absolute; top: var(--hitbox-t, 0px); right: var(--hitbox-r, 0px); bottom: var(--hitbox-b, 0px); left: var(--hitbox-l, 0px); pointer-events: inherit; }
      }
      @utility hitbox-b-* {
        position: relative;
        --hitbox-b: calc(-1 * --spacing(--value(number, [*])));
        &::before { content: ""; position: absolute; top: var(--hitbox-t, 0px); right: var(--hitbox-r, 0px); bottom: var(--hitbox-b, 0px); left: var(--hitbox-l, 0px); pointer-events: inherit; }
      }
      @utility hitbox-x-* {
        position: relative;
        --hitbox-l: calc(-1 * --spacing(--value(number, [*])));
        --hitbox-r: calc(-1 * --spacing(--value(number, [*])));
        &::before { content: ""; position: absolute; top: var(--hitbox-t, 0px); right: var(--hitbox-r, 0px); bottom: var(--hitbox-b, 0px); left: var(--hitbox-l, 0px); pointer-events: inherit; }
      }
      @utility hitbox-y-* {
        position: relative;
        --hitbox-t: calc(-1 * --spacing(--value(number, [*])));
        --hitbox-b: calc(-1 * --spacing(--value(number, [*])));
        &::before { content: ""; position: absolute; top: var(--hitbox-t, 0px); right: var(--hitbox-r, 0px); bottom: var(--hitbox-b, 0px); left: var(--hitbox-l, 0px); pointer-events: inherit; }
      }
      ```

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
<Button className="hitbox-6">Click me</Button>
<Checkbox className="hitbox-4" />
<a href="/page" className="hitbox-y-3 block py-2">Link</a>
```

## Examples [#examples]

### Basic [#basic]

Use `hitbox-*` to extend the hit area uniformly on all sides.

<ComponentPreview componentName="hitbox" fileName="example-basic" />

### Individual sides [#individual-sides]

Target specific sides with `hitbox-l-*`, `hitbox-r-*`, `hitbox-t-*`, and `hitbox-b-*`.

<ComponentPreview componentName="hitbox" fileName="example-sides" />

### Horizontal and vertical [#horizontal-and-vertical]

Use `hitbox-x-*` and `hitbox-y-*` for axis shorthands.

<ComponentPreview componentName="hitbox" fileName="example-axes" />

### Custom values [#custom-values]

Use arbitrary values with bracket syntax.

<ComponentPreview componentName="hitbox" fileName="example-custom" />

### Debugging [#debugging]

Add `hitbox-debug` to visualize the expanded hit area.

<ComponentPreview componentName="hitbox" fileName="example-debug" />

### Sidebar navigation [#sidebar-navigation]

Use `hitbox-y-*` so adjacent items feel continuous.

<ComponentPreview componentName="hitbox" fileName="example-sidebar" />

## API Reference [#api-reference]

| Class          | Expansion                        |
| -------------- | -------------------------------- |
| `hitbox`       | Base (no expansion)              |
| `hitbox-*`     | All sides (spacing or `[value]`) |
| `hitbox-l-*`   | Left                             |
| `hitbox-r-*`   | Right                            |
| `hitbox-t-*`   | Top                              |
| `hitbox-b-*`   | Bottom                           |
| `hitbox-x-*`   | Left and right                   |
| `hitbox-y-*`   | Top and bottom                   |
| `hitbox-debug` | Debug overlay                    |


# JSON Tree View (/docs/utilities/json-tree-view)



<ComponentPreview componentName="json-tree-view" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/json-tree-view
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react lucide-react
      ```

      <Step>
        Import the following variables into your CSS file
      </Step>

      <CodeCollapsibleWrapper>
        ```css
        @theme inline {
          --color-destructive-foreground: var(--destructive-foreground);
          --color-info: var(--info);
          --color-info-foreground: var(--info-foreground);
          --color-success: var(--success);
          --color-success-foreground: var(--success-foreground);
          --color-warning: var(--warning);
          --color-warning-foreground: var(--warning-foreground);
        }

        :root {
          --destructive-foreground: var(--color-red-700);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-700);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-700);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-700);
        }

        .dark {
          --destructive-foreground: var(--color-red-400);
          --info: var(--color-blue-500);
          --info-foreground: var(--color-blue-400);
          --success: var(--color-emerald-500);
          --success-foreground: var(--color-emerald-400);
          --warning: var(--color-amber-500);
          --warning-foreground: var(--color-amber-400);
        }
        ```
      </CodeCollapsibleWrapper>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/json-tree-view.tsx" src="/json-tree-view.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { JsonTreeView } from "@/registry/react/components/json-tree-view";

const data = { name: "John", age: 30, address: { city: "NYC" } };

<JsonTreeView data={data} defaultExpandedDepth={1} />
```

## Examples [#examples]

### Different data types [#different-data-types]

Display various JavaScript data types including objects, arrays, primitives, dates, and special values.

<ComponentPreview componentName="json-tree-view" fileName="example-data-types" />

### Controlling expand level [#controlling-expand-level]

Use the `defaultExpandedDepth` prop to control how many levels are expanded by default.

<ComponentPreview componentName="json-tree-view" fileName="example-expand-depth" />

### Map and Set [#map-and-set]

Native JavaScript Map and Set objects are supported.

<ComponentPreview componentName="json-tree-view" fileName="example-map-set" />

## API Reference [#api-reference]

### JsonTreeView [#jsontreeview]

| Prop                   | Type                  | Default |
| ---------------------- | --------------------- | ------- |
| `data`                 | `object`              | -       |
| `defaultExpandedDepth` | `number`              | -       |
| `renderValue`          | `(node) => ReactNode` | -       |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/utilities/json-tree-view#api-reference).


# Presence (/docs/utilities/presence)



<ComponentPreview componentName="presence" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/presence
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/presence.tsx" src="/presence.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import React from "react";
import { Presence } from "@/registry/react/components/presence";

const [visible, setVisible] = React.useState(false);

<Presence present={visible}>
  Content that animates in and out
</Presence>
```

## Lazy [#lazy]

Setting `lazyMount` and `unmountOnExit` to `true` lazy mounts and unmounts the content.

It will remove the element from the DOM when it is not present.

```tsx showLineNumbers
<Presence lazyMount unmountOnExit {...}>
  {/** content */}
</Presence>
```

## States [#states]

Presence automatically manages the attribute `data-state` to `open` and `closed`. This enables styling and animations based on visibility state.

```tsx showLineNumbers
<Presence present={true} /> // <div data-state="open" />
<Presence present={false} /> // <div data-state="closed" />
```

## API Reference [#api-reference]

### Presence [#presence]

| Prop            | Type      | Default |
| --------------- | --------- | ------- |
| `present`       | `boolean` | `false` |
| `unmountOnExit` | `boolean` | `true`  |
| `lazyMount`     | `boolean` | `true`  |
| `asChild`       | `boolean` | `false` |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/utilities/presence#api-reference).


# Show (/docs/utilities/show)



<ComponentPreview componentName="show" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/show
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/show.tsx" src="/show.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Show } from "@/registry/react/components/show";
```

```tsx
<Show when={isLoading} fallback={<Spinner />}>
 {/** content */}
</Show>
```

## API Reference [#api-reference]

### Show [#show]

| Prop       | Type              | Default  |
| ---------- | ----------------- | -------- |
| `when`     | `boolean`         | required |
| `fallback` | `React.ReactNode` | -        |
| `children` | `React.ReactNode` | required |


# Swap (/docs/utilities/swap)



<ComponentPreview componentName="swap" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      CLI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @shark/swap
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @ark-ui/react tailwind-variants
      ```

      <Step>
        Add the following keyframes to your 

        `globals.css`

         for the flip variant:
      </Step>

      ```css title="globals.css"
      @theme inline {
        --animate-flip-in: flip-in 0.2s ease-out;
        --animate-flip-out: flip-out 0.2s ease-out;

        @keyframes flip-in {
          from {
            transform: rotateY(180deg);
          }
          to {
            transform: rotateY(0deg);
          }
        }

        @keyframes flip-out {
          from {
            transform: rotateY(0deg);
          }
          to {
            transform: rotateY(180deg);
          }
        }
      }
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource title="components/ui/swap.tsx" src="/swap.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { 
  Swap, 
  SwapIndicator
} from "@/registry/react/components/swap";
```

```tsx
<Swap>
  <SwapIndicator type="on">
    <MoonIcon />
  </SwapIndicator>
  <SwapIndicator type="off">
    <SunIcon />
  </SwapIndicator>
</Swap>
```

## Examples [#examples]

### Fade [#fade]

<ComponentPreview componentName="swap" fileName="example-default" />

### Flip [#flip]

<ComponentPreview componentName="swap" fileName="example-flip" />

### Rotate [#rotate]

<ComponentPreview componentName="swap" fileName="example-rotate" />

### Scale [#scale]

<ComponentPreview componentName="swap" fileName="example-scale" />

### Blur [#blur]

<ComponentPreview componentName="swap" fileName="example-blur" />

## API Reference [#api-reference]

### Swap [#swap]

| Prop            | Type                                                | Default  |
| --------------- | --------------------------------------------------- | -------- |
| `variant`       | `"fade" \| "scale" \| "flip" \| "rotate" \| "blur"` | `"fade"` |
| `swap`          | `boolean`                                           | `-`      |
| `lazyMount`     | `boolean`                                           | `true`   |
| `unmountOnExit` | `boolean`                                           | `true`   |
| `className`     | `string`                                            | `-`      |
| `asChild`       | `boolean`                                           | `-`      |

### SwapIndicator [#swapindicator]

| Prop        | Type            | Default      |
| ----------- | --------------- | ------------ |
| `type`      | `'on' \| 'off'` | **required** |
| `className` | `string`        | `-`          |
| `asChild`   | `boolean`       | `-`          |

***

For a complete list of props, see the [Ark UI documentation](https://ark-ui.com/docs/utilities/swap#api-reference).