# COSS for Svelte

**COSS for Svelte** is an unofficial Svelte 5 port of COSS UI. It uses Shards UI for headless
behavior, Tailwind CSS for styling, and the shadcn-svelte CLI for registry installation.

Unofficial Svelte port made by Miel: https://github.com/mielsense

## Overview

- [Introduction](https://coss-sv.vercel.app/docs/index.md): A modern Svelte 5 component library built on Shards UI. Built for developers and AI.
- [Get Started](https://coss-sv.vercel.app/docs/get-started.md): A quick guide to adding your first Svelte component.
- [Styling](https://coss-sv.vercel.app/docs/styling.md): Configure COSS color, radius, typography, and overlay tokens with Tailwind CSS v4.
- [Migrating from shadcn-svelte and Bits UI](https://coss-sv.vercel.app/docs/radix-migration.md): Move an existing Svelte component set to the Shards-backed COSS for Svelte wrappers.
- [Agent Skill](https://coss-sv.vercel.app/docs/skills.md): Teach coding agents how to install, compose, and debug COSS for Svelte components.
- [Changelog](https://coss-sv.vercel.app/docs/changelog.md): Breaking changes, migration guides, and notable updates.
- [Roadmap](https://coss-sv.vercel.app/docs/roadmap.md): Current state of coss ui and where we’re headed next.

## Components

- [Accordion](https://coss-sv.vercel.app/docs/components/accordion.md): A set of collapsible panels with headings and content.
- [Alert](https://coss-sv.vercel.app/docs/components/alert.md): A callout for displaying important information.
- [Alert Dialog](https://coss-sv.vercel.app/docs/components/alert-dialog.md): A dialog that requires user response to proceed.
- [Autocomplete](https://coss-sv.vercel.app/docs/components/autocomplete.md): An input that suggests options as you type.
- [Avatar](https://coss-sv.vercel.app/docs/components/avatar.md): An image element with a fallback for representing the user.
- [Badge](https://coss-sv.vercel.app/docs/components/badge.md): A badge or a component that looks like a badge.
- [Breadcrumb](https://coss-sv.vercel.app/docs/components/breadcrumb.md): Displays the path to the current resource using a hierarchy of links.
- [Button](https://coss-sv.vercel.app/docs/components/button.md): A button or a component that looks like a button.
- [Calendar](https://coss-sv.vercel.app/docs/components/calendar.md): A date picker component with range and multi-select support.
- [Card](https://coss-sv.vercel.app/docs/components/card.md): A content container for grouping related information.
- [Checkbox](https://coss-sv.vercel.app/docs/components/checkbox.md): A control allowing the user to toggle between checked and not checked.
- [Checkbox Group](https://coss-sv.vercel.app/docs/components/checkbox-group.md): Provides shared state to a series of checkboxes.
- [Collapsible](https://coss-sv.vercel.app/docs/components/collapsible.md): A collapsible panel controlled by a button trigger.
- [Combobox](https://coss-sv.vercel.app/docs/components/combobox.md): An input combined with a list of predefined items to select.
- [Command](https://coss-sv.vercel.app/docs/components/command.md): A command palette component built with Dialog and Autocomplete for searching and executing commands.
- [Context Menu](https://coss-sv.vercel.app/docs/components/context-menu.md): A menu that appears at the pointer on right click or long press.
- [Date Picker](https://coss-sv.vercel.app/docs/components/date-picker.md): A date picker component built with Calendar and Popover.
- [Dialog](https://coss-sv.vercel.app/docs/components/dialog.md): A popup that opens on top of the entire page.
- [Drawer](https://coss-sv.vercel.app/docs/components/drawer.md): A panel that slides in from the edge of the screen with swipe gestures, snap points, and nested drawer support.
- [Empty](https://coss-sv.vercel.app/docs/components/empty.md): A container for displaying empty state information.
- [Field](https://coss-sv.vercel.app/docs/components/field.md): A component that provides labelling and validation for form controls.
- [Fieldset](https://coss-sv.vercel.app/docs/components/fieldset.md): A native fieldset element with a legend.
- [Form](https://coss-sv.vercel.app/docs/components/form.md): A form wrapper component that simplifies validation and submission.
- [Frame](https://coss-sv.vercel.app/docs/components/frame.md): A framed container for grouping related information.
- [Group](https://coss-sv.vercel.app/docs/components/group.md): A component for visually grouping a series of controls.
- [Input](https://coss-sv.vercel.app/docs/components/input.md): A native input element.
- [Input Group](https://coss-sv.vercel.app/docs/components/input-group.md): A flexible component for grouping inputs with addons, buttons, and other elements.
- [Kbd](https://coss-sv.vercel.app/docs/components/kbd.md): A component for displaying keyboard keys and shortcuts.
- [Label](https://coss-sv.vercel.app/docs/components/label.md): Renders an accessible label associated with controls.
- [Menu](https://coss-sv.vercel.app/docs/components/menu.md): A list of actions in a dropdown, enhanced with keyboard navigation.
- [Meter](https://coss-sv.vercel.app/docs/components/meter.md): A graphical display of a numeric value within a range.
- [Number Field](https://coss-sv.vercel.app/docs/components/number-field.md): A numeric input element with increment and decrement buttons, and a scrub area.
- [OTP Field](https://coss-sv.vercel.app/docs/components/otp-field.md): A segmented input for one-time passwords and verification codes.
- [Pagination](https://coss-sv.vercel.app/docs/components/pagination.md): A pagination with page navigation, next and previous links.
- [Popover](https://coss-sv.vercel.app/docs/components/popover.md): An accessible popup anchored to a button.
- [Preview Card](https://coss-sv.vercel.app/docs/components/preview-card.md): A popup that appears when a link is hovered, showing a preview for sighted users.
- [Progress](https://coss-sv.vercel.app/docs/components/progress.md): Displays the status of a task that takes a long time.
- [Radio Group](https://coss-sv.vercel.app/docs/components/radio-group.md): A set of checkable buttons where no more than one of the buttons can be checked at a time.
- [Scroll Area](https://coss-sv.vercel.app/docs/components/scroll-area.md): A native scroll container with custom scrollbars.
- [Select](https://coss-sv.vercel.app/docs/components/select.md): A common form component for choosing a predefined value in a dropdown menu.
- [Segmented Control](https://coss-sv.vercel.app/docs/components/segmented-control.md): A visual pattern for presenting related choices, navigation destinations, filters, or content views.
- [Separator](https://coss-sv.vercel.app/docs/components/separator.md): A separator element accessible to screen readers.
- [Sheet](https://coss-sv.vercel.app/docs/components/sheet.md): A flyout that opens from the side of the screen, based on the dialog component.
- [Skeleton](https://coss-sv.vercel.app/docs/components/skeleton.md): A loading state skeleton for your components.
- [Slider](https://coss-sv.vercel.app/docs/components/slider.md): An input where the user selects a value from within a given range.
- [Spinner](https://coss-sv.vercel.app/docs/components/spinner.md): An indicator that can be used to show a loading state.
- [Switch](https://coss-sv.vercel.app/docs/components/switch.md): A control that indicates whether a setting is on or off.
- [Table](https://coss-sv.vercel.app/docs/components/table.md): A simple table component for displaying tabular data.
- [Tabs](https://coss-sv.vercel.app/docs/components/tabs.md): A component for toggling between related panels on the same page.
- [Textarea](https://coss-sv.vercel.app/docs/components/textarea.md): A native textarea element.
- [Toast](https://coss-sv.vercel.app/docs/components/toast.md): A temporary notification that appears on screen to inform users.
- [Toggle](https://coss-sv.vercel.app/docs/components/toggle.md): A two-state button that can be toggled on or off.
- [Toggle Group](https://coss-sv.vercel.app/docs/components/toggle-group.md): Provides a shared state to a series of toggle buttons.
- [Toolbar](https://coss-sv.vercel.app/docs/components/toolbar.md): A container for grouping a set of buttons and controls.
- [Tooltip](https://coss-sv.vercel.app/docs/components/tooltip.md): A popup that appears when an element is hovered or focused, showing a hint for sighted users.

## Svelte patterns

- [useMediaQuery](https://coss-sv.vercel.app/docs/hooks/use-media-query.md): Reactive media query helper with Tailwind-like syntax.
- [useCopyToClipboard](https://coss-sv.vercel.app/docs/hooks/use-copy-to-clipboard.md): Copy text to the clipboard with temporary copied feedback.


---

# Full documentation

## Document: Introduction

# Introduction

> A modern Svelte 5 component library built on Shards UI. Built for developers and AI.

[Canonical documentation](https://coss-sv.vercel.app/docs)

**COSS for Svelte** is a collection of beautifully designed, accessible, and composable components
for Svelte 5 applications. Built on top of [Shards UI](https://shardsui.com) and styled with
[Tailwind CSS](https://tailwindcss.com), it is designed for you to copy, paste, and own.

We think Shards UI is the right behavioral foundation for this port. We take its unstyled Svelte
primitives and apply the COSS design system, examples, states, and interaction details.

The original [COSS UI](https://coss.com/ui) is the component library being progressively adopted by
[Cal.com](https://cal.com). This independent port brings that library to Svelte without changing the
visual design.

<EarlyAccessCallout>
  COSS for Svelte is in active development. Components, documentation, and registry items are being
  reviewed against the pinned COSS reference, and Shards UI may still introduce API changes. Use it
  in projects where you are comfortable adapting to changes before the first stable release.
</EarlyAccessCallout>

## How It Works

Our approach is simple: you should own your code. We follow the copy-paste ethos of **shadcn-svelte**.

Instead of installing an opaque component package, you get the source code. This means:

- **No abstractions:** You have full control over how components look and behave.
- **Endless customization:** Need to change something? Edit the generated file.
- **Learn by doing:** See how components are built and adapt them to your needs.

## Built on Shards UI, Designed for Production

COSS for Svelte is built on **Shards UI** from the ground up. Shards supplies accessible,
unopinionated primitives that handle keyboard navigation, focus management, selection, overlays, and
positioning without imposing a visual design.

This port is not a restyled shadcn-svelte component set. It is a **coherent, opinionated UI system
that follows the pinned COSS reference**, including:

- **Production-tested patterns** from real applications
- **Extended component variants** for common use cases
- **Thoughtful defaults** optimized for modern, dense interfaces
- **A consistent design system** across every component

If you are migrating from shadcn-svelte or direct Bits UI components, read the
[migration guide](/docs/radix-migration).

## Primitives, Particles and Atoms

At the core of COSS are the **UI primitives**: accessible building blocks whose behavior is powered
by Shards UI and whose visible design comes from COSS.

On top of these primitives are [particles](/particles). Particles are **pre-assembled components**,
such as authentication forms, tables, or date pickers, that combine several primitives into
ready-to-use solutions. They are more opinionated, but remain easy to customize or break apart.

The original COSS ecosystem also includes [atoms](https://cal.com/atoms). Atoms are **API-enhanced
particles** that connect interface patterns to external data and services. Atoms are not part of this
Svelte component-library port.

Together, the layers form a spectrum:

- **Primitives** → the foundation
- **Particles** → the patterns
- **Atoms** → the integrations

This lets you choose the right level of abstraction: a bare component, a polished interface pattern,
or an API-connected solution.

## Built for Humans and AI

The source is written to be clear, readable, and predictable, so people and language models can
understand, reason about, and modify it. Each documentation page also has a plain-text Markdown route.

## Open Source, Made Sustainable

This port preserves the open-source intent of COSS. It adapts only the MIT-designated
`reference/apps/ui` source boundary, records the pinned upstream revision, and keeps the attribution
visible. See [Credits](/credits) for the exact provenance and license links.

COSS for Svelte is an independent project and is not endorsed by COSS, Cal.com, or their
contributors.

## Get Involved

Bug reports, accessibility findings, component mismatches, and documentation fixes are welcome. A
useful report names the component or particle, includes the viewport and theme, and links to the
matching COSS reference example.


---

## Document: Get Started

# Get Started

> A quick guide to adding your first Svelte component.

[Canonical documentation](https://coss-sv.vercel.app/docs/get-started)

This guide provides the essentials for adding **COSS for Svelte** components to your Svelte 5
application.

## Prerequisites

Our components are built with [Tailwind CSS v4](https://tailwindcss.com). Before you begin, make sure
you have a Svelte 5 project set up with Tailwind CSS and pnpm.

## Adding components

You can add components **automatically with the shadcn-svelte CLI** or **manually by copying the
files**. Both methods work for primitives and particles.

### With the CLI

Each component page provides a command to add it to your project automatically. The CLI creates the
necessary files and installs the dependencies declared by that registry item.

### New project setup

For a new project, initialize shadcn-svelte first:

```bash
pnpm dlx shadcn-svelte@latest init
```

Review the aliases selected by the initializer. Registry files use those aliases when the CLI writes
imports into your project. Then add the component from the exact registry URL shown on its page:

```bash
pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/button.json
```

Unlike the upstream React registry, this Svelte port does not publish an aggregate style preset yet.
Add the global theme from the [Styling](/docs/styling) guide once, then install the component files you
need.

### Existing projects

To add components to an existing project, pass each registry URL to the shadcn-svelte CLI:

```bash
pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/button.json https://coss-sv.vercel.app/r/card.json
```

The CLI can install several registry items in one command:

```bash
pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/avatar.json https://coss-sv.vercel.app/r/dialog.json https://coss-sv.vercel.app/r/tabs.json
```

See the [Styling](/docs/styling) guide for the color tokens, sidebar variables, and base styles.

### Manual installation

1. **Find a component** on the [Components](/docs) or [Particles](/particles) pages.
2. **Copy the code** from the **Code** tab.
3. **Create the matching `.svelte` and `.ts` files** in your project and keep their relative paths.
4. **Install every dependency** listed by the registry item with pnpm.
5. **Import and use** the component in your app.

## Styling

Components use the design token system from **COSS UI** and Cal.com. CSS variables define the
tokens, and Tailwind CSS consumes them.

The variables are compatible with shadcn-svelte and fully customizable. Change them in your global
stylesheet, usually `src/app.css`, to match your design system.

COSS introduces a few additional tokens for more granular control:

- `--destructive-foreground`: destructive-outline buttons, destructive menu items, badges, and field
  errors
- `--info` and `--info-foreground`: info badges, toast types, and alerts
- `--success` and `--success-foreground`: success badges, toast types, and alerts
- `--warning` and `--warning-foreground`: warning badges, toast types, and alerts

**Important:** the component registry items do not replace your global stylesheet. Add these tokens
from the [Styling](/docs/styling) guide when setting up the port.

## Fonts

COSS components use three CSS custom properties for typography:

- `--font-sans` controls body text, buttons, labels, and most UI elements.
- `--font-mono` controls code blocks, `<kbd>`, and monospace text.
- `--font-heading` controls Dialog, Alert Dialog, Sheet, Card, and Empty titles.

COSS UI uses Inter and Geist Mono in its default style preset. The reference website uses Cal Sans
2.0 for body and headings. This port keeps the same variable contract without forcing a font package.

### Custom fonts

Define the variables in your global stylesheet. When sans and heading share one family, alias
`--font-heading` to `--font-sans`:

```css
:root {
  --font-sans: "Inter Variable", sans-serif;
  --font-heading: var(--font-sans);
  --font-mono: "Geist Mono Variable", monospace;
}
```

For a separate heading family, assign it directly:

```css
:root {
  --font-heading: "Cal Sans", sans-serif;
}
```

If fonts appear broken after setup, check that the custom properties use the exact names above and
that the font files load before the component stylesheet.

## Primitive exports

Components that wrap Shards UI re-export the underlying primitive namespace. Use the styled COSS
parts when the defaults work, or the primitive when you need a different composition.

```svelte
<script lang="ts">
  import * as Slider from "$lib/components/ui/slider/index.js";
</script>

<Slider.Root value={40}>
  <Slider.Control>
    <Slider.Track><Slider.Indicator /></Slider.Track>
    <Slider.Thumb />
  </Slider.Control>
</Slider.Root>
```

For direct primitive access, import the explicit `SliderPrimitive` export from the same module. An
application that already owns the generated COSS files does not need a second direct Shards import.

## Shards UI re-exports

Behavioral component directories expose their Shards namespace as an explicit `*Primitive` export,
such as `DialogPrimitive`, `MenuPrimitive`, and `SelectPrimitive`. This is useful in a monorepo: apps
can compose against the generated COSS module while keeping the Shards version in one place.

## Migration from shadcn-svelte and Bits UI

For developers migrating from **shadcn-svelte** or direct **Bits UI** components, the
[migration guide](/docs/radix-migration) translates the equivalent component structures to COSS for
Svelte and Shards UI. It covers namespace imports, trigger composition, bindings, item data, and
callback contracts.

## Working with coding agents

The documentation gives coding agents the component structure and local rules they need to make
changes. It includes:

- An installable [Agent Skill](/docs/skills) with the component catalog, Svelte conventions, and
  registry workflow used by this port.
- An [llms.txt](/llms.txt) file that maps the documentation and component structure for an agent.
- A **Copy Markdown** button on every guide in this lane for sharing exact page content with a coding
  agent.


---

## Document: Styling

# Styling

> Configure COSS color, radius, typography, and overlay tokens with Tailwind CSS v4.

[Canonical documentation](https://coss-sv.vercel.app/docs/styling)

## Overview

This library is optimized for specific semantic color tokens that provide crisp, contrasted borders
and visual depth. The styling system builds on
[shadcn-svelte's CSS-variable approach](https://www.shadcn-svelte.com/docs/theming) for consistency
and maintainability.

Components use translucent borders instead of solid colors. Those borders mix with small bottom
shadows to stay crisp even when the background lacks contrast.

The color system is optional, but it provides the intended visual result. Conventional tokens may
produce borders and shadows with different contrast.

The Svelte orange `#ff3e00` belongs to this documentation site's navigation and links. It is not a
component token. Installed components keep the neutral COSS theme shown below.

## Installation

See [Get Started](/docs/get-started) for installation with the shadcn-svelte CLI. To add the theme
manually, paste these tokens into the Tailwind stylesheet imported by your root layout.

```css title="src/app.css"
@custom-variant dark (&:is(.dark *));

@theme inline {
  --font-sans: var(--font-sans);
  --font-heading: var(--font-sans);
  --font-mono: var(--font-mono);
  --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);
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
  --animate-skeleton: skeleton 2s -1s infinite linear;

  @keyframes skeleton {
    to {
      background-position: -200% 0;
    }
  }
}

:root {
  --radius: 0.625rem;
  --background: var(--color-white);
  --foreground: var(--color-neutral-800);
  --card: var(--color-white);
  --card-foreground: var(--color-neutral-800);
  --popover: var(--color-white);
  --popover-foreground: var(--color-neutral-800);
  --primary: var(--color-neutral-800);
  --primary-foreground: var(--color-neutral-50);
  --secondary: --alpha(var(--color-black) / 4%);
  --secondary-foreground: var(--color-neutral-800);
  --muted: --alpha(var(--color-black) / 4%);
  --muted-foreground: color-mix(in srgb, var(--color-neutral-500) 90%, var(--color-black));
  --accent: --alpha(var(--color-black) / 4%);
  --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: --alpha(var(--color-black) / 8%);
  --input: --alpha(var(--color-black) / 10%);
  --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: --alpha(var(--color-black) / 4%);
  --sidebar-accent-foreground: var(--color-neutral-800);
  --sidebar-border: --alpha(var(--color-black) / 6%);
  --sidebar-ring: var(--color-neutral-400);
}

.dark {
  --background: color-mix(in srgb, var(--color-neutral-950) 96%, var(--color-white));
  --foreground: var(--color-neutral-100);
  --card: color-mix(in srgb, var(--background) 98%, var(--color-white));
  --card-foreground: var(--color-neutral-100);
  --popover: color-mix(in srgb, var(--background) 96%, var(--color-white));
  --popover-foreground: var(--color-neutral-100);
  --primary: var(--color-neutral-100);
  --primary-foreground: var(--color-neutral-800);
  --secondary: --alpha(var(--color-white) / 4%);
  --secondary-foreground: var(--color-neutral-100);
  --muted: --alpha(var(--color-white) / 4%);
  --muted-foreground: color-mix(in srgb, var(--color-neutral-500) 90%, var(--color-white));
  --accent: --alpha(var(--color-white) / 4%);
  --accent-foreground: var(--color-neutral-100);
  --destructive: color-mix(in srgb, var(--color-red-500) 90%, var(--color-white));
  --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: --alpha(var(--color-white) / 6%);
  --input: --alpha(var(--color-white) / 8%);
  --ring: var(--color-neutral-500);
  --sidebar: color-mix(in srgb, var(--color-neutral-950) 97%, var(--color-white));
  --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: --alpha(var(--color-white) / 4%);
  --sidebar-accent-foreground: var(--color-neutral-100);
  --sidebar-border: --alpha(var(--color-white) / 5%);
  --sidebar-ring: var(--color-neutral-400);
}
```

## Font Variables

Components use three font variables.

- `--font-sans` controls body text, controls, and labels.
- `--font-mono` controls code and keyboard shortcuts.
- `--font-heading` controls dialog, alert dialog, sheet, and empty-state titles.

Set the variables on `html` or `body` so they cascade into portals. By default, the theme maps
`--font-heading` to `--font-sans`.

```css
:root {
  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
  --font-mono: "Geist Mono", ui-monospace, monospace;
}
```

### Custom fonts

Set the three properties to any loaded fonts. When sans and heading share one family, only
`--font-sans` needs a distinct value because the theme aliases `--font-heading` to it.

For a separate heading family, point the theme token at that variable:

```css title="src/app.css"
:root {
  --font-sans: "Inter Variable", sans-serif;
  --font-heading: "Cal Sans", sans-serif;
  --font-mono: "Geist Mono Variable", monospace;
}

@theme inline {
  --font-heading: var(--font-heading);
}
```

Apply the variables to `html` or `body` so they cascade through the application and its portals.

## Shards UI Setup

Shards UI renders overlays through portals. Give the application root its own stacking context and
make `body` the containing block for full-viewport backdrops.

### Application Root Isolation

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import "../app.css";
  import type { Snippet } from "svelte";

  let { children }: { children: Snippet } = $props();
</script>

<div class="relative isolate flex min-h-svh flex-col">
  {@render children()}
</div>
```

This creates a local stacking context so portalled components stay above page content without
component-specific z-index overrides.

### iOS Safari Compatibility

```css title="src/app.css"
body {
  position: relative;
}
```

This keeps portalled dialogs, sheets, popovers, selects, and menus above application content. It also
prevents backdrop gaps after scrolling in current iOS Safari.


---

## Document: Migrating from shadcn-svelte and Bits UI

# Migrating from shadcn-svelte and Bits UI

> Move an existing Svelte component set to the Shards-backed COSS for Svelte wrappers.

[Canonical documentation](https://coss-sv.vercel.app/docs/radix-migration)

The upstream COSS guide helps React applications move from Radix and shadcn/ui to COSS and Base UI.
For this port, the equivalent job is moving a Svelte application from shadcn-svelte or direct Bits UI
parts to the COSS wrappers backed by Shards UI.

Do not translate React props literally. Install one component at a time, compare its current Svelte
types, then test its keyboard and focus behavior before removing the old implementation.

## Overview

COSS for Svelte uses compound namespace imports for behavioral components. The root owns shared state,
and nested parts read it through context.

```svelte
<script lang="ts">
  import * as Dialog from "$lib/components/ui/dialog/index.js";
</script>

<Dialog.Root>
  <Dialog.Trigger>Open dialog</Dialog.Trigger>
  <Dialog.Popup>
    <Dialog.Header>
      <Dialog.Title>Edit profile</Dialog.Title>
      <Dialog.Description>Change the account details below.</Dialog.Description>
    </Dialog.Header>
    <Dialog.Panel>Form fields go here.</Dialog.Panel>
    <Dialog.Footer>
      <Dialog.Close>Cancel</Dialog.Close>
    </Dialog.Footer>
  </Dialog.Popup>
</Dialog.Root>
```

## General migration patterns

### Use namespaces and an explicit root

Replace a flat list of component imports with a namespace for compound components.

```svelte
<script lang="ts">
  import * as Accordion from "$lib/components/ui/accordion/index.js";
</script>

<Accordion.Root defaultValue={["item-1"]}>
  <Accordion.Item value="item-1">
    <Accordion.Header>
      <Accordion.Trigger>Account</Accordion.Trigger>
    </Accordion.Header>
    <Accordion.Panel>Account settings</Accordion.Panel>
  </Accordion.Item>
</Accordion.Root>
```

### Replace render delegation with native parts

Shards parts render the correct native element and forward HTML attributes. Style a trigger directly
instead of wrapping a Button solely to delegate its element.

```svelte
<script lang="ts">
  import { buttonVariants } from "$lib/components/ui/button/index.js";
  import * as Dialog from "$lib/components/ui/dialog/index.js";
</script>

<Dialog.Root>
  <Dialog.Trigger class={buttonVariants({ variant: "outline" })}>Open dialog</Dialog.Trigger>
  <Dialog.Popup>...</Dialog.Popup>
</Dialog.Root>
```

Use the `as` prop only when a part should render another HTML tag. It accepts a tag name, not a
component.

```svelte
<Menu.Item as="a" href="/settings">Settings</Menu.Item>
```

### Bind state with Svelte

Replace controlled value boilerplate with bindings. Callback props remain available when the change
needs a side effect.

```svelte
<script lang="ts">
  import * as Dialog from "$lib/components/ui/dialog/index.js";
  let open = $state(false);
</script>

<Dialog.Root bind:open onOpenChange={(next) => console.log(next)}>...</Dialog.Root>
```

Common bindings include `bind:open`, `bind:value`, `bind:checked`, and `bind:ref`.

### Use `class` and lowercase event attributes

Svelte uses `class`, not `className`, and current event attributes such as `onclick`, not React event
props or legacy directives.

```svelte
<Menu.Item class="text-destructive" onclick={() => archiveProject()}>Archive project</Menu.Item>
```

### Component naming conventions

The Svelte namespace keeps the same clearer part names introduced by COSS:

- `*.Content` becomes `*.Popup` for positioned surfaces or `*.Panel` for scrollable body content.
- Legacy aliases may exist for compatibility, but new code should use the documented namespace name.
- Compound components use an explicit `*.Root`; simple elements such as Button and Input remain named
  exports.

## Component migration guides

### Accordion

- Use `Accordion.Root`, `Item`, `Header`, `Trigger`, and `Panel`.
- Values are arrays for both single and multiple selection.
- Set `multiple` to allow more than one open item.
- Use `bind:value` or `onValueChange` for controlled state.

**Comparison example:**

```svelte title="shadcn-svelte"
<Accordion.Root type="multiple" value="item-1">
  <Accordion.Item value="item-1">
    <Accordion.Trigger>Title</Accordion.Trigger>
    <Accordion.Content>Content</Accordion.Content>
  </Accordion.Item>
</Accordion.Root>
```

```svelte title="COSS for Svelte"
<Accordion.Root multiple defaultValue={["item-1"]}>
  <Accordion.Item value="item-1">
    <Accordion.Header>
      <Accordion.Trigger>Title</Accordion.Trigger>
    </Accordion.Header>
    <Accordion.Panel>Content</Accordion.Panel>
  </Accordion.Item>
</Accordion.Root>
```

### Alert

Alert remains a single element component. COSS adds semantic `info`, `success`, `warning`, and
`error` variants. Add the semantic color variables from the [Styling](/docs/styling) guide.

### Badge

Badge remains a named component. It adds `sm`, `default`, and `lg` sizes; use `lg` when preserving the
height of a typical shadcn-svelte badge. It also adds the semantic variants listed for Alert.

When the whole badge navigates, render it as an anchor directly:

```svelte
<Badge as="a" href="/new">New</Badge>
```

### Button

COSS buttons are denser than the corresponding shadcn-svelte defaults and include more sizes.

| Size      | Typical shadcn-svelte height | COSS height |
| --------- | ---------------------------- | ----------- |
| `xs`      | Not available                | 24px        |
| `sm`      | 32px                         | 28px        |
| `default` | 36px                         | 32px        |
| `lg`      | 40px                         | 36px        |
| `xl`      | Not available                | 40px        |
| `icon`    | 36px                         | 32px        |
| `icon-sm` | Not available                | 28px        |
| `icon-lg` | Not available                | 36px        |

Use `lg` to preserve a 36px default control. The `destructive-outline` variant is appropriate for a
secondary destructive trigger; reserve the solid `destructive` variant for the primary destructive
action.

Buttons render anchors when `href` is present:

```svelte
<Button href="/login">Login</Button>
```

### Input

Input sizes are `sm` at 28px, `default` at 32px, and `lg` at 36px. Use `lg` when preserving the
typical 36px shadcn-svelte input height.

### Alert Dialog

- Use `AlertDialog.Popup` instead of `Content` in new code.
- Compose Header and Footer directly inside Popup; Alert Dialog has no separate Panel part.
- Replace separate Action and Cancel parts with `AlertDialog.Close` controls.
- Bind `open` on the root when application state needs it.

```svelte
<AlertDialog.Root>
  <AlertDialog.Trigger class={buttonVariants({ variant: "outline" })}>
    Show Alert Dialog
  </AlertDialog.Trigger>
  <AlertDialog.Popup>
    <AlertDialog.Header>
      <AlertDialog.Title>Are you absolutely sure?</AlertDialog.Title>
      <AlertDialog.Description>This action cannot be undone.</AlertDialog.Description>
    </AlertDialog.Header>
    <AlertDialog.Footer>
      <AlertDialog.Close class={buttonVariants({ variant: "ghost" })}>Cancel</AlertDialog.Close>
      <AlertDialog.Close class={buttonVariants({ variant: "destructive" })}>
        Continue
      </AlertDialog.Close>
    </AlertDialog.Footer>
  </AlertDialog.Popup>
</AlertDialog.Root>
```

### Dialog

- Use `Dialog.Popup` instead of `Content` in new code.
- Put `Header`, `Panel`, and `Footer` in that order.
- Keep a form that spans Panel and Footer at `class="contents"`.
- Use `Dialog.Close` for controls that dismiss the overlay.

```svelte
<Dialog.Root>
  <Dialog.Trigger class={buttonVariants({ variant: "outline" })}>Show Dialog</Dialog.Trigger>
  <Dialog.Popup>
    <Dialog.Header>
      <Dialog.Title>Dialog Title</Dialog.Title>
      <Dialog.Description>Dialog Description</Dialog.Description>
    </Dialog.Header>
    <Dialog.Panel>Content</Dialog.Panel>
    <Dialog.Footer>
      <Dialog.Close class={buttonVariants({ variant: "ghost" })}>Cancel</Dialog.Close>
    </Dialog.Footer>
  </Dialog.Popup>
</Dialog.Root>
```

### Sheet

Sheet follows the Dialog structure with `Sheet.Popup`, `Sheet.Header`, `Sheet.Panel`, and
`Sheet.Footer`.

```svelte
<Sheet.Root>
  <Sheet.Trigger class={buttonVariants({ variant: "outline" })}>Open Sheet</Sheet.Trigger>
  <Sheet.Popup>
    <Sheet.Header><Sheet.Title>Sheet Title</Sheet.Title></Sheet.Header>
    <Sheet.Panel>Content here</Sheet.Panel>
    <Sheet.Footer>
      <Sheet.Close class={buttonVariants()}>Close</Sheet.Close>
    </Sheet.Footer>
  </Sheet.Popup>
</Sheet.Root>
```

### Group (Button Group)

- Prefer the `Group.*` names; legacy Button Group aliases may remain for compatibility.
- Place `Group.Separator` between adjacent controls, including outline buttons, so focus states and
  borders remain consistent.
- Render text or icons directly in `Group.Text` rather than introducing an extra control.

### Input Group

Use the regular Button inside `InputGroup.Addon`; there is no separate Input Group Button component.
To disable the group, disable `InputGroup.Input` or `InputGroup.Textarea` and any Button inside the
group. Do not add a manual `data-disabled` attribute to the wrapper.

### Avatar and links

Use the root as an anchor when the whole avatar navigates.

```svelte
<Avatar.Root as="a" href="/profile">
  <Avatar.Image alt="User" src="/avatar.jpg" />
  <Avatar.Fallback>U</Avatar.Fallback>
</Avatar.Root>
```

### Card

Use `Card.Panel` for the main card body. `Card.Content` remains a compatibility alias.

### Checkbox

Checkbox remains a named component. Bind `checked` for a controlled value, and pass labels through a
native `<label>` or the COSS Label component.

```svelte
<Label><Checkbox bind:checked /> Accept the terms</Label>
```

### Collapsible

Use `Collapsible.Panel` for content and bind `open` on `Collapsible.Root` when needed. Style the COSS
trigger part directly instead of wrapping a second button.

```svelte
<Collapsible.Root>
  <Collapsible.Trigger class={buttonVariants({ variant: "outline" })}>Toggle</Collapsible.Trigger>
  <Collapsible.Panel>Content here</Collapsible.Panel>
</Collapsible.Root>
```

### Command

The Command API is data driven. Pass an `items` array to the root and render collections inside their
groups. Use `Command.DialogRoot`, `Command.DialogTrigger`, and `Command.DialogPopup` for dialog mode.

```svelte
<script lang="ts">
  import * as Command from "$lib/components/ui/command/index.js";

  type CommandItem = {
    label: string;
    value: string;
  };

  type CommandGroup = {
    label: string;
    items: CommandItem[];
  };

  const groups: CommandGroup[] = [
    {
      label: "Pages",
      items: [
        { label: "Calendar", value: "calendar" },
        { label: "Settings", value: "settings" },
      ],
    },
    {
      label: "Actions",
      items: [
        { label: "Create event", value: "create-event" },
        { label: "Invite member", value: "invite-member" },
      ],
    },
  ];
</script>

<Command.DialogRoot>
  <Command.DialogTrigger>Open command menu</Command.DialogTrigger>
  <Command.DialogPopup aria-label="Command menu">
    <Command.Root items={groups}>
      <Command.Input aria-label="Search commands" placeholder="Search commands…" />
      <Command.Panel>
        <Command.Empty>No results found.</Command.Empty>
        <Command.List>
          <Command.Collection>
            {#snippet children(group: CommandGroup)}
              <Command.Group items={group.items}>
                <Command.GroupLabel>{group.label}</Command.GroupLabel>
                <Command.Collection>
                  {#snippet children(item: CommandItem)}
                    <Command.Item value={item}>{item.label}</Command.Item>
                  {/snippet}
                </Command.Collection>
              </Command.Group>
            {/snippet}
          </Command.Collection>
        </Command.List>
      </Command.Panel>
    </Command.Root>
  </Command.DialogPopup>
</Command.DialogRoot>
```

- The Svelte port has no `cmdk` dependency.
- `Command.GroupLabel` is a child, not a `heading` prop.
- Render `Command.Collection` inside `Command.Group` for grouped data.
- Read the [Command documentation](/docs/components/command) before migrating a custom filter or
  virtualization layer.

### Menu

- Use `Menu.Popup` and `Menu.SubPopup`.
- Action items use `onclick`.
- Navigation rows use `Menu.LinkItem` with `href`.
- Checkbox and radio items support Svelte bindings.

```svelte
<Menu.Root>
  <Menu.Trigger>Open menu</Menu.Trigger>
  <Menu.Popup>
    <Menu.Item onclick={() => edit()}>Edit</Menu.Item>
    <Menu.LinkItem href="/settings">Settings</Menu.LinkItem>
  </Menu.Popup>
</Menu.Root>
```

When migrating a shadcn-svelte Dropdown Menu, rename the namespace and use current Svelte event
attributes:

```diff
- <DropdownMenu.Root>
-   <DropdownMenu.Trigger>Open menu</DropdownMenu.Trigger>
-   <DropdownMenu.Content>
-     <DropdownMenu.Item on:select={openDashboard}>Dashboard</DropdownMenu.Item>
-   </DropdownMenu.Content>
- </DropdownMenu.Root>
+ <Menu.Root>
+   <Menu.Trigger>Open menu</Menu.Trigger>
+   <Menu.Popup>
+     <Menu.Item onclick={openDashboard}>Dashboard</Menu.Item>
+   </Menu.Popup>
+ </Menu.Root>
```

### Context Menu

Context Menu uses the same Popup, Item, LinkItem, checkbox, radio, group, and submenu vocabulary as
Menu. Its root opens from right click or long press rather than a trigger click. Use
`ContextMenu.LinkItem` for navigation rows.

### OTP Field

Use one `OTPField.Input` for each character. The root takes `length`; inputs follow DOM order and do
not take an index.

```svelte
<script lang="ts">
  import * as OTPField from "$lib/components/ui/otp-field/index.js";
  let value = $state("");
</script>

<OTPField.Root aria-label="Verification code" bind:value length={6}>
  {#each Array(3) as _, index (index)}
    <OTPField.Input aria-label={index === 0 ? undefined : `Character ${index + 1} of 6`} />
  {/each}
  <OTPField.Separator />
  {#each Array(3) as _, index (index)}
    <OTPField.Input aria-label={`Character ${index + 4} of 6`} />
  {/each}
</OTPField.Root>
```

### Popover

Use `Popover.Popup` in new code. Popover also provides `Title`, `Description`, and `Close`. Bind
`open` on the root for controlled state.

```svelte
<Popover.Root>
  <Popover.Trigger class={buttonVariants({ variant: "outline" })}>Open Popover</Popover.Trigger>
  <Popover.Popup>
    <Popover.Title>Popover Title</Popover.Title>
    <Popover.Description>Popover Description</Popover.Description>
    <Popover.Close class={buttonVariants({ variant: "ghost" })}>Close</Popover.Close>
  </Popover.Popup>
</Popover.Root>
```

### Preview Card

Rename Hover Card imports to Preview Card and use `PreviewCard.Popup` in place of Content.

```svelte
<PreviewCard.Root>
  <PreviewCard.Trigger class={buttonVariants({ variant: "outline" })}>
    Open Preview Card
  </PreviewCard.Trigger>
  <PreviewCard.Popup>Preview Card Content</PreviewCard.Popup>
</PreviewCard.Root>
```

### Progress

The root renders the normal track and indicator when it has no children. For a custom composition,
include `Progress.Track` and `Progress.Indicator` yourself. `Progress.Label` and `Progress.Value`
connect visible text to the meter semantics.

### Radio Group

Use `RadioGroup.Root` with `RadioGroup.Item` for each option. Bind the string value on the root and
associate each item with visible label text.

```svelte
<RadioGroup.Root bind:value>
  <Label><RadioGroup.Item value="comfortable" /> Comfortable</Label>
  <Label><RadioGroup.Item value="compact" /> Compact</Label>
</RadioGroup.Root>
```

### Scroll Area

Use `ScrollArea.Root`, `Viewport`, and the exported scrollbar parts. Add `overscrollContain` only for
nested surfaces that must not chain scroll to a parent. Add `fill` only when inner flex content must
stretch to the viewport height.

### Select

Pass `items` to the root so the selected label is available during server rendering. Bind the selected
value and render the same values as items.

```svelte
<script lang="ts">
  import * as Select from "$lib/components/ui/select/index.js";

  const frameworks = [
    { label: "Select a framework", value: null },
    { label: "SvelteKit", value: "sveltekit" },
    { label: "Vite", value: "vite" },
    { label: "Astro", value: "astro" },
  ];
  let framework = $state<string | null>(null);
</script>

<Select.Root aria-label="Framework" bind:value={framework} items={frameworks}>
  <Select.Trigger><Select.Value /></Select.Trigger>
  <Select.Popup alignItemWithTrigger={false}>
    {#each frameworks as item (item.value)}
      <Select.Item value={item.value}>{item.label}</Select.Item>
    {/each}
  </Select.Popup>
</Select.Root>
```

### Slider

The Svelte wrapper accepts a scalar for one thumb and an array for multiple thumbs. Bind `value` with
the same shape you pass initially.

```svelte
<Slider value={50} />
<Slider value={[25, 75]} />
```

### Switch

Switch remains a named component. Bind `checked` for controlled state and use a Label for visible
text.

```svelte
<Label><Switch bind:checked /> Airplane mode</Label>
```

### Tabs

Use `Tabs.Tab` and `Tabs.Panel`. The list supports `default` and `underline` variants plus `sm`,
`default`, and `lg` sizes.

```svelte
<Tabs.Root defaultValue="tab-1">
  <Tabs.List>
    <Tabs.Tab value="tab-1">Tab 1</Tabs.Tab>
    <Tabs.Tab value="tab-2">Tab 2</Tabs.Tab>
    <Tabs.Tab value="tab-3">Tab 3</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="tab-1">Tab 1 content</Tabs.Panel>
  <Tabs.Panel value="tab-2">Tab 2 content</Tabs.Panel>
  <Tabs.Panel value="tab-3">Tab 3 content</Tabs.Panel>
</Tabs.Root>
```

### Textarea

Textarea sizes are `sm`, `default`, and `lg`. Match the size used by adjacent Input and Select
controls so a form retains a consistent density.

### Toast

Wrap the application content in `Toast.Provider` and call a manager from event handlers.

```svelte
<script lang="ts">
  import * as Toast from "$lib/components/ui/toast/index.js";
  const manager = new Toast.Manager();
</script>

<Toast.Provider toastManager={manager}>
  <button
    type="button"
    onclick={() => manager.add({ title: "Event has been created", type: "success" })}
  >
    Create event
  </button>
</Toast.Provider>
```

### Toggle

The standalone Toggle remains a named component. Bind `pressed` when application state needs to read
or change it. Do not confuse it with `ToggleGroup.Item`.

### Toggle Group

Use `multiple` for multi-select groups. Values are arrays in both single and multiple mode, and each
option is `ToggleGroup.Item`.

```svelte
<ToggleGroup.Root defaultValue={["bold"]} multiple>
  <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
  <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item>
</ToggleGroup.Root>
```

### Tooltip

Use `Tooltip.Popup` instead of Content. Wrap related tooltips in one Provider and style the Trigger
part directly.

```svelte
<Tooltip.Provider>
  <Tooltip.Root>
    <Tooltip.Trigger class={buttonVariants({ variant: "outline" })}>Hover me</Tooltip.Trigger>
    <Tooltip.Popup>Tooltip content</Tooltip.Popup>
  </Tooltip.Root>
</Tooltip.Provider>
```

## Verify after migration

- Run `pnpm check` and the affected tests.
- Open every overlay with the keyboard, close it with Escape, and confirm focus returns to its trigger.
- Verify labels, descriptions, invalid state, selected state, and form values.
- Compare density, spacing, borders, focus rings, and dark theme with the matching COSS example.
- Check server output and hydration logs for missing selected labels or generated ID changes.

## Additional resources

- [Component documentation](/docs)
- [Styling guide](/docs/styling)
- [Shards UI documentation](https://shardsui.com/svelte)
- [shadcn-svelte documentation](https://www.shadcn-svelte.com)

## Need help?

Check the individual component page, compare the rendered result with the matching COSS reference,
and read the local Shards documentation for the primitive's state and keyboard contract. If the
mismatch remains, open an issue with a reproduction, viewport, theme, and expected COSS example.


---

## Document: Agent Skill

# Agent Skill

> Teach coding agents how to install, compose, and debug COSS for Svelte components.

[Canonical documentation](https://coss-sv.vercel.app/docs/skills)

The `coss-svelte` skill gives a coding agent the port-specific context it needs before changing a
component. Install it once, then ask the agent to use it whenever it adds, customizes, migrates, or
debugs COSS for Svelte.

## Install the agent skill

Install the skill directly from this repository:

```bash
npx skills add mielsense/coss-sv --skill coss-svelte
```

The installed skill includes a component catalog and an implementation guide. It directs the agent
to the current Svelte documentation before choosing a registry item, import, compound part, prop, or
state contract.

[Read the skills CLI documentation](https://skills.sh/docs), or [review the published
SKILL.md](/skill.md) before installing it. The GitHub command works directly and does not depend on a
skills.sh directory listing.

## What the skill covers

- The complete component catalog and the current Markdown documentation routes
- Registry installation with the shadcn-svelte CLI and the documented `$lib/` alias
- Svelte namespace composition such as `Card.Header`, `Dialog.Popup`, and `InputGroup.Addon`
- The boundary between the COSS visual contract and Shards UI behavior
- Controlled state, callback details, overlay handles, and toast managers
- Tailwind tokens, component variants, Hugeicons, accessibility, and reduced motion
- A debugging order for registry, composition, state, layout, and keyboard problems

The skill treats the current Svelte page as the public contract. It does not translate Base UI or
React APIs from the original project into consumer code.

## Ask an agent to use it

Name the skill and the outcome you want:

```text
Use the coss-svelte skill to add an accessible settings dialog with a labelled form and save and
cancel actions. Start from the closest documented particle.
```

For a compound control, ask the agent to preserve Svelte namespace composition:

```text
Use the coss-svelte skill to build a searchable country selector. Verify the exact Combobox API,
keyboard behavior, focus return, and reduced-motion state before changing component source.
```

## Without an installed skill

Agents that cannot install repository skills can read [the documentation index](/llms.txt), [the
full documentation snapshot](/llms-full.txt), or the Markdown form of any page, such as [the Button
guide](/docs/components/button.md). The same skill and bundled references are also published under
`/.well-known/agent-skills/coss-svelte/`.


---

## Document: Changelog

# Changelog

> Breaking changes, migration guides, and notable updates.

[Canonical documentation](https://coss-sv.vercel.app/docs/changelog)

## Upstream COSS history

The dated entries below preserve the pinned upstream COSS changelog. They describe the React library
and retain the original commands, API names, migration prompts, and links as historical source
material.

## August 19, 2026

### Tabs sizing and segmented control styles

**`TabsList`** now supports a **`size`** prop with **`"sm"`**, **`"default"`**, and **`"lg"`** values. The size propagates to its **`TabsTab`** children, and an individual tab can override the inherited size when necessary.

The default Tabs appearance now uses the same optical item sizing as the [Segmented Control](/docs/components/segmented-control) pattern. The default rendered height is slightly smaller than before so the inset active indicator remains visually balanced beside a Button of the corresponding size.

Tabs now imports its size map and **`segmentedControlItemLayoutClassName`** from the **`@coss/segmented-control`** registry library. That class covers the shared icon gap, size, and opacity treatment. **`segmentedControlItemVariants`** includes it, and **`TabsTab`** uses it instead of inlining the same utilities. **`@coss/tabs`** declares this as a registry dependency, so the shadcn CLI installs it automatically with a fresh installation or CLI-managed update.

**Migration:**

Existing Tabs JSX requires no changes because **`"default"`** remains the default size. If you replace your local Tabs component through the CLI, review any local customizations before accepting the overwrite:

<!-- prettier-ignore -->
~~~bash
npx shadcn@latest add @coss/tabs
~~~

If you update **`tabs.tsx`** manually, install the shared library first and then merge the latest Tabs implementation. Copying only the new Tabs file without this dependency results in an unresolved import.

<!-- prettier-ignore -->
~~~bash
npx shadcn@latest add @coss/segmented-control
~~~

After updating, remove local height or horizontal-padding utilities from **`TabsList`** and **`TabsTab`** only where they unintentionally override the new **`size`** API. Keep intentional product-specific overrides. If you maintain a local copy of the library or Tabs, also merge **`segmentedControlItemLayoutClassName`** so icons stay optically aligned with Button.

**Agent migration prompt:**

```text
Update the local coss Tabs component to the latest segmented-control sizing and item layout while preserving project-specific customizations. Install the shared registry dependency with `npx shadcn@latest add @coss/segmented-control`, then merge the latest @coss/tabs implementation. TabsList now accepts size="sm" | "default" | "lg" (default: "default") and propagates it to TabsTab; a TabsTab size prop overrides the inherited value. Replace the old hard-coded TabsTab height and horizontal-padding classes with segmentedControlItemSizeClassNames from the shared library, and replace inlined icon gap/size/opacity utilities with segmentedControlItemLayoutClassName. Existing Tabs JSX does not need a size prop. Audit local h-* and px-* overrides on TabsList/TabsTab and remove only those that unintentionally conflict with the new size API. Run formatting and typechecking, then visually verify default and underline Tabs in every size used by the app.
```

## July 31, 2026

### Scroll Area — overscroll contain

**`ScrollArea`** no longer applies **`overscroll-behavior: contain`** by default. Use the new optional **`overscrollContain`** prop (default **`false`**) to opt in.

Nested surfaces that should not chain scroll to the page already pass it: **`DialogPanel`**, **`SheetPanel`**, **`DrawerPanel`**, **`ComboboxList`**, **`AutocompleteList`**, and **`SidebarContent`**.

**Migration:**

No change required for those composed parts after upgrading. For custom nested scroll areas (command menus, calendar time lists, vendored **`sidebar.tsx`**, etc.), opt in explicitly:

<!-- prettier-ignore -->
~~~diff
- <ScrollArea scrollbarGutter scrollFade>
+ <ScrollArea overscrollContain scrollbarGutter scrollFade>
~~~

**Agent migration prompt:**

```text
After upgrading @coss/scroll-area, ScrollArea no longer applies overscroll-contain by default. Add overscrollContain only on nested scroll surfaces where wheel/touch should not chain to a parent scroller (dialogs, sheets, drawers, popups, sidebars, command panels). DialogPanel, SheetPanel, DrawerPanel, ComboboxList, AutocompleteList, and SidebarContent already pass overscrollContain—update local copies of those components if you vendor them.
```

## July 26, 2026

### React DayPicker 10

coss ui now targets **`@daypicker/react@10`**. The legacy **`react-day-picker`** package name remains available for compatibility, but DayPicker recommends the scoped package for v10 and newer.

If you import DayPicker APIs directly, update the dependency and imports:

<!-- prettier-ignore -->
~~~diff
- import { DayPicker, type DateRange } from "react-day-picker"
+ import { DayPicker, type DateRange } from "@daypicker/react"
~~~

DayPicker v10 removes APIs deprecated in v9, including legacy navigation props, aliases, component slots, and `classNames` / `styles` keys. Applications with custom calendar wrappers should follow the [DayPicker v10 migration guide](https://daypicker.dev/upgrading).

**Agent migration prompt:**

```text
Upgrade React DayPicker to v10. Replace the react-day-picker dependency with @daypicker/react and update all imports, including style and locale imports. Audit custom Calendar and DatePicker wrappers for APIs removed in v10: replace deprecated navigation and focus props, aliases, component slots, and classNames/styles keys according to https://daypicker.dev/upgrading. If the app uses a non-Gregorian calendar, install the corresponding @daypicker/* add-on and update its imports. Run the typecheck and test affected date-picker screens after migrating.
```

## June 22, 2026

### Base UI 1.6.0

coss ui now targets **`@base-ui/react@1.6.0`**.

**Breaking change covered in this bump:** Base UI renamed the OTP namespace export from **`OTPFieldPreview`** to **`OTPField`**. coss has been updated accordingly in the OTP field implementation and docs.

If you import Base UI OTP primitives directly in your app, update:

<!-- prettier-ignore -->
~~~diff
- import { OTPFieldPreview } from "@base-ui/react/otp-field"
+ import { OTPField } from "@base-ui/react/otp-field"
~~~

## June 11, 2026

### Context Menu

**`@coss/context-menu`** is a new registry component for right-click and long-press action menus anchored to the pointer. See the [Context Menu](/docs/components/context-menu) docs for installation and examples.

**Install:**

<!-- prettier-ignore -->
~~~bash
npx shadcn@latest add @coss/context-menu
~~~

No migration from an existing coss primitive—opt in where you need pointer-triggered menus instead of (or alongside) **`Menu`**.

### Menu & Context Menu — link items

**`MenuLinkItem`** and **`ContextMenuLinkItem`** are styled wrappers for Base UI **`LinkItem`**. They match **`MenuItem`** / **`ContextMenuItem`** visually and default **`closeOnClick`** to **`true`** so the menu closes on navigation.

**`LinkItem`** renders a native **`<a>`** when you pass **`href`**. If you were already using **`render={<Link href="..." />}`** (or another router link), **keep `render`** on the link item — swap the component name only, do not drop `render` for `href` alone.

Use **`href`** only for plain anchor links with no router **`Link`**.

**Migration:**

<!-- prettier-ignore -->
~~~diff
  import {
    Menu,
-   MenuItem,
+   MenuLinkItem,
    MenuPopup,
    MenuTrigger,
  } from "$lib/components/ui/menu"
~~~

<!-- prettier-ignore -->
~~~diff
- <MenuItem render={<Link href="/docs" />}>Docs</MenuItem>
+ <MenuLinkItem render={<Link href="/docs" />}>Docs</MenuLinkItem>
~~~

Plain anchor (no router **`Link`**):

<!-- prettier-ignore -->
~~~tsx
<MenuLinkItem href="/docs">Docs</MenuLinkItem>
~~~

For context menus:

<!-- prettier-ignore -->
~~~diff
- <ContextMenuItem render={<Link href="/docs" />}>Docs</ContextMenuItem>
+ <ContextMenuLinkItem render={<Link href="/docs" />}>Docs</ContextMenuLinkItem>
~~~

Existing **`MenuItem render={<Link … />}`** usage keeps working; migrate when you touch those menus.

**Agent migration prompt:**

```text
coss now exports MenuLinkItem (menu.tsx) and ContextMenuLinkItem (context-menu.tsx) for navigation rows. Replace MenuItem/ContextMenuItem with render={<Link href="..." />} by changing only the component to MenuLinkItem/ContextMenuLinkItem — keep render={<Link … />}; do not replace render with href when using Next.js or another router Link. Use href on MenuLinkItem/ContextMenuLinkItem only for plain <a> navigation without a router Link. Keep MenuItem/ContextMenuItem for actions (onClick), not navigation. Context Menu is a new @coss/context-menu package—see Context Menu docs.
```

## May 29, 2026

### Scroll Area

**`ScrollArea`** adds an optional **`fill`** prop (default **`false`**). When **`fill`** is enabled, **`size-full`** is applied to **`ScrollArea.Content`** so inner flex layouts can use the full viewport height (for example, pinning a footer with **`mt-auto`** in a sidebar).

Most scroll areas should keep the default. Opt in only when the scroll container must stretch rather than size to its children.

**Migration:**

No change required for existing **`ScrollArea`** usage (lists, dialogs, comboboxes, command menus). For custom sidebars or other flex columns with **`mt-auto`** footers inside a scroll area, opt in explicitly:

<!-- prettier-ignore -->
~~~diff
- <ScrollArea className="flex-1 min-h-0">
+ <ScrollArea className="flex-1 min-h-0" fill>
    <div className="flex h-full flex-col">
      …
      <footer className="mt-auto">…</footer>
    </div>
  </ScrollArea>
~~~

**`SidebarContent`** from **`@coss/sidebar`** already passes **`fill`**—update your local **`sidebar.tsx`** copy if you vendor the component.

**Agent migration prompt:**

```text
After upgrading @coss/scroll-area, ScrollArea has an optional fill prop (default false). Do not add fill to every ScrollArea. Add fill only where a flex column inside the scroll area must stretch to the viewport height (e.g. mt-auto footer in a sidebar). Pair fill with flex-1 min-h-0 on the ScrollArea and h-full flex-col on the inner wrapper. SidebarContent in @coss/sidebar already uses fill.
```

## Apr 17, 2026

### Form

The **`Form`** component (`form.tsx`) no longer applies default layout classes (`flex`, `flex-col`, `gap-4`, `w-full`). It is a thin wrapper around Base UI only; pass **`className`** wherever you need a vertical field stack, width constraints, or dialog/sheet layout.

**Migration:**

For a typical stacked-field form, restore the previous default explicitly:

<!-- prettier-ignore -->
~~~diff
- <Form onSubmit={…}>
+ <Form className="flex w-full flex-col gap-4" onSubmit={…}>
~~~

For **dialogs, sheets, and drawers**, keep **`DialogHeader`** (or **`SheetHeader`**, **`DrawerHeader`**) **outside** the form. Wrap **`DialogPanel`** and **`DialogFooter`** (or sheet/drawer equivalents) in **`<Form className="contents">`** or a native **`<form className="contents">`**. **`display: contents`** keeps **header, panel, and footer** as the **direct flex children** of the popup’s column layout so **`DialogPanel`** scroll and height constraints work correctly.

**Agent migration prompt:**

```text
The coss Form component no longer adds default Tailwind layout. Add className="flex w-full flex-col gap-4" to Form where you relied on the old stacked-field layout. For dialog/sheet/drawer: put header outside the form; wrap only panel+footer in Form (or native form) with className="contents". Merge any existing Form className with flex utilities where needed (e.g. max-w-64 becomes flex w-full max-w-64 flex-col gap-4).
```

## Apr 14, 2026

### OTP Field

The **`input-otp.tsx`** registry component has been removed in favor of **`otp-field.tsx`** (`@coss/otp-field`), which wraps Base UI OTP Field. See the [OTP Field](/docs/components/otp-field) docs and [migration guide](/docs/radix-migration#otp-field) for API details.

**Migration:**

<!-- prettier-ignore -->
~~~diff
- npx shadcn@latest add @coss/input-otp
+ npx shadcn@latest add @coss/otp-field
~~~

<!-- prettier-ignore -->
~~~diff
- import { ... } from "$lib/components/ui/input-otp"
+ import { ... } from "$lib/components/ui/otp-field"
~~~

**Agent migration prompt:**

```text
Replace the removed @coss/input-otp / components/ui/input-otp.tsx with @coss/otp-field / components/ui/otp-field.tsx. Follow the OTP Field docs: use OTPField, OTPFieldInput, and OTPFieldSeparator; use length on the root; remove the old input-otp npm package if present.
```

## Apr 12, 2026

### Table

`Table` now supports an optional **`variant`** prop: **`"default"`** (the default) or **`"card"`**. Omitting it keeps the same appearance as before. Use **`variant="card"`** for the card-style grid (separated rows, rounded cells, updated hover/footer treatment)—including tables inside a [Frame](/docs/components/frame) or [CardFrame](/docs/components/card) as shown in the [Table docs](/docs/components/table).

**Migration:**

No change required for existing tables. Opt in where you want the card-style table:

<!-- prettier-ignore -->
~~~tsx
<Table variant="card">
~~~

**Agent migration prompt:**

```text
After upgrading @coss/table, Table supports an optional variant prop: "default" (default) or "card". Existing Table components require no edits. Add variant="card" to Table where you want the card-style table (e.g. inside Frame or CardFrame). Do not add variant to every table—only where the design calls for the card-style grid.
```

## Mar 20, 2026

### Toggle Group

`Toggle` was renamed to `ToggleGroupItem` in `toggle-group.tsx` to avoid a naming conflict with the standalone `Toggle` export.

**Migration:**

<!-- prettier-ignore -->
~~~diff
- import { Toggle, ToggleGroup } from "$lib/components/ui/toggle-group"
+ import { ToggleGroup, ToggleGroupItem } from "$lib/components/ui/toggle-group"
~~~

<!-- prettier-ignore -->
~~~diff
  <ToggleGroup>
-   <Toggle value="bold">Bold</Toggle>
+   <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
  </ToggleGroup>
~~~

**Agent migration prompt:**

```text
In my codebase, rename all usages of `Toggle` imported from `toggle-group` to `ToggleGroupItem`. Update both the import statements and JSX usage. Do not change `Toggle` imports from `toggle.tsx` (standalone toggle). Only change files that import `Toggle` from the `toggle-group` module.
```

## Svelte port status

COSS for Svelte tracks the same dated design changes where they apply, but its generated components
use Svelte 5, Shards UI, pnpm, and shadcn-svelte. The React migration prompts above are preserved as
upstream history; do not run them against a Svelte project.

Install or refresh a Svelte registry item with its current documentation command. For example:

```bash
pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/tabs.json
```

Before accepting generated changes, compare local customizations and run the project typecheck,
interaction tests, and visual checks for the affected component.


---

## Document: Roadmap

# Roadmap

> Current state of coss ui and where we’re headed next.

[Canonical documentation](https://coss-sv.vercel.app/docs/roadmap)

## Upstream COSS roadmap

**coss ui** is the evolution of **Origin UI**, an open-source collection of React and Tailwind
components created by Pasquale Vitiello and Davide Pacilio. It was recently **acquired by Cal.com**
and grown into a broader, more ambitious ecosystem, with Pasquale contributing directly to the
development of the new UI.

Our goal is to **bring together the best parts of Origin UI** with a stronger foundation—Base UI
primitives—so developers get not just components, but a layered system of **primitives**,
**particles**, and **atoms**.

## Origin UI

Origin UI offered a large collection of 600+ ready-to-use UI components. With the **transition to
coss ui**:

- The existing **Origin UI components** will evolve into **particles**—higher-level UI patterns
  composed of Base UI primitives.
- The original Origin UI collection remains available on [this page](https://coss.com/origin), so
  developers can continue to access it during the transition.

## Current Status

- **50+ UI primitives** already available, with more on the way.
- A **growing set of particles**, progressively expanding to match and surpass the current Origin UI
  collection.

## What’s Next

- Expand the **primitives set**, ensuring full coverage of common UI needs.
- Add more **particles**, aligning with and eventually replacing the original Origin UI collection.
- Introduce **atoms**, API-enhanced components that bring external integrations out of the box.

## Svelte port status

COSS for Svelte ports the primitives, particles, documentation, and registry items from the pinned
COSS reference. Each implementation receives separate parity, accessibility, and Svelte-quality
review before integration.

The first release targets the pinned primitive and particle catalog, the shadcn-svelte registry, and
agent-readable Markdown routes. It does not include atoms or the legacy Origin application. This
repository adapts source only from the MIT-designated COSS `reference/apps/ui` subtree.


---

## Document: Accordion

# Accordion

> A set of collapsible panels with headings and content.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/accordion)

<ComponentPreview name="p-accordion-1" align="start" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/accordion.json" />

## Usage

```svelte
<script lang="ts">
  import * as Accordion from "$lib/components/ui/accordion/index.js";
</script>

<Accordion.Root>
  <Accordion.Item value="item-1">
    <Accordion.Header>
      <Accordion.Trigger>Is it accessible?</Accordion.Trigger>
    </Accordion.Header>
    <Accordion.Panel>Yes. It adheres to the WAI-ARIA design pattern.</Accordion.Panel>
  </Accordion.Item>
</Accordion.Root>
```

## API Reference

### Accordion.Root

The root component owns single or multiple selection. Use `value` and `bind:value` for controlled
state, or `defaultValue` for the initial uncontrolled value.

### Accordion.Item

An individual accordion item. Each item needs a unique `value` and keeps the COSS bottom border.

### Accordion.Header

The heading wrapper for an item trigger.

### Accordion.Trigger

The button that toggles its panel. It includes the COSS chevron, which rotates when the item opens.

### Accordion.Panel

The collapsible content panel. It uses the Shards accordion measurements and transition state while
keeping the COSS height animation. `Accordion.Content` is an alias.

See the [Shards Accordion API](https://shardsui.com/svelte/accordion) for primitive state, keyboard,
and accessibility props.

## Examples

### Single Accordion

<ComponentPreview name="p-accordion-2" align="start" />

### Multiple Accordion

<ComponentPreview name="p-accordion-3" align="start" />

### Controlled Accordion

<ComponentPreview name="p-accordion-4" align="start" />


---

## Document: Alert

# Alert

> A callout for displaying important information.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/alert)

<ComponentPreview name="p-alert-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/alert.json" />

## Usage

```svelte
<script lang="ts">
  import * as Alert from "$lib/components/ui/alert/index.js";
</script>

<Alert.Root>
  <Alert.Title>Heads up!</Alert.Title>
  <Alert.Description>
    You can add components and dependencies to your app using the CLI.
  </Alert.Description>
</Alert.Root>
```

## API Reference

This is a custom component, not a Shards UI wrapper.

### Alert.Root

Root container for the alert. Native `div` attributes pass to the rendered element.

| Prop      | Type                                                       | Default     | Description                                 |
| --------- | ---------------------------------------------------------- | ----------- | ------------------------------------------- |
| `variant` | `"default" \| "error" \| "info" \| "success" \| "warning"` | `"default"` | Controls the alert styling and color scheme |

### Alert.Title

Title text for the alert. Renders as a styled `div`.

### Alert.Description

Description text for the alert. Renders as a styled `div` with muted foreground color.

### Alert.Action

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

## Examples

### With Icon

<ComponentPreview name="p-alert-2" />

### With Icon and Action Buttons

<ComponentPreview name="p-alert-3" />

### Info Alert

<ComponentPreview name="p-alert-4" />

### Success Alert

<ComponentPreview name="p-alert-5" />

### Warning Alert

<ComponentPreview name="p-alert-6" />

### Error Alert

<ComponentPreview name="p-alert-7" />


---

## Document: Alert Dialog

# Alert Dialog

> A dialog that requires user response to proceed.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/alert-dialog)

<ComponentPreview name="p-alert-dialog-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/alert-dialog.json" />

## Usage

```svelte
<script lang="ts">
  import * as AlertDialog from "$lib/components/ui/alert-dialog/index.js";
</script>

<AlertDialog.Root>
  <AlertDialog.Trigger>Delete Account</AlertDialog.Trigger>
  <AlertDialog.Popup>
    <AlertDialog.Header>
      <AlertDialog.Title>Are you absolutely sure?</AlertDialog.Title>
      <AlertDialog.Description>
        This action cannot be undone. This will permanently delete your account and remove your data
        from our servers.
      </AlertDialog.Description>
    </AlertDialog.Header>
    <AlertDialog.Footer>
      <AlertDialog.Close>Cancel</AlertDialog.Close>
      <AlertDialog.Close>Delete Account</AlertDialog.Close>
    </AlertDialog.Footer>
  </AlertDialog.Popup>
</AlertDialog.Root>
```

## API Reference

### AlertDialog.Root

Root component. Wraps `AlertDialog.Root` from Shards UI.

### AlertDialog.Trigger

Trigger button that opens the alert dialog. Wraps `AlertDialog.Trigger` from Shards UI.

### AlertDialog.Popup

Popup container that displays the alert dialog content. Also exported as `AlertDialog.Content`.

| Prop                  | Type                                        | Default | Description                                                                                                          |
| --------------------- | ------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `bottomStickOnMobile` | `boolean`                                   | `true`  | When true, sticks to the bottom of the screen on mobile devices                                                      |
| `portalProps`         | `ComponentProps<typeof AlertDialog.Portal>` | -       | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see the Shards UI Alert Dialog portal API |

### AlertDialog.Header

Container for the alert dialog title and description.

### AlertDialog.Footer

Footer section for action buttons.

Unlike [Dialog](/docs/components/dialog), alert dialog has no `AlertDialog.Panel`. Put title and description in `AlertDialog.Header`, actions in `AlertDialog.Footer`, and use a plain element with `class` if you need extra body content between them.

| Prop      | Type                  | Default     | Description                                                                                |
| --------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `variant` | `"default" \| "bare"` | `"default"` | Controls the footer styling. `default` includes border and background, `bare` removes them |

**Example:**

```svelte
<!-- Default variant (with border and background) -->
<AlertDialog.Footer>
  <AlertDialog.Close>Cancel</AlertDialog.Close>
  <AlertDialog.Close>Delete</AlertDialog.Close>
</AlertDialog.Footer>

<!-- Bare variant (no border or background) -->
<AlertDialog.Footer variant="bare">
  <AlertDialog.Close>Cancel</AlertDialog.Close>
  <AlertDialog.Close>Delete</AlertDialog.Close>
</AlertDialog.Footer>
```

### AlertDialog.Title

Title component. Wraps `AlertDialog.Title` from Shards UI.

### AlertDialog.Description

Description component. Wraps `AlertDialog.Description` from Shards UI.

### AlertDialog.Close

Close button component. Wraps `AlertDialog.Close` from Shards UI.

### AlertDialog.Portal

Portal component for rendering outside the DOM hierarchy. Wraps `AlertDialog.Portal` from Shards UI.

### AlertDialog.Backdrop

Backdrop/overlay component. Also exported as `AlertDialog.Overlay`. Wraps `AlertDialog.Backdrop` from Shards UI.

### AlertDialog.Viewport

Viewport component for positioning. Wraps `AlertDialog.Viewport` from Shards UI.

## Examples

### Alert Dialog with Bare Footer

<ComponentPreview name="p-alert-dialog-2" />

### Close Confirmation

<ComponentPreview name="p-dialog-4" />


---

## Document: Autocomplete

# Autocomplete

> An input that suggests options as you type.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/autocomplete)

<ComponentPreview name="p-autocomplete-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/autocomplete.json" />

## Usage

```svelte
<script lang="ts">
  import * as Autocomplete from "$lib/components/ui/autocomplete/index.js";

  const items = [
    { value: "apple", label: "Apple" },
    { value: "banana", label: "Banana" },
    { value: "orange", label: "Orange" },
    { value: "grape", label: "Grape" },
  ];
</script>

<Autocomplete.Root {items}>
  <Autocomplete.Input placeholder="Search..." />
  <Autocomplete.Popup>
    <Autocomplete.Empty>No results found.</Autocomplete.Empty>
    <Autocomplete.List>
      <Autocomplete.Collection>
        {#snippet children(item)}
          <Autocomplete.Item value={item}>{item.label}</Autocomplete.Item>
        {/snippet}
      </Autocomplete.Collection>
    </Autocomplete.List>
  </Autocomplete.Popup>
</Autocomplete.Root>
```

## API Reference

### Autocomplete.Root

The root autocomplete component. Manages the autocomplete state and provides context to child components.

| Prop       | Type                                       | Description                                       |
| ---------- | ------------------------------------------ | ------------------------------------------------- |
| `items`    | `readonly unknown[]`                       | The array of items to display in the autocomplete |
| `open`     | `boolean`                                  | Controls whether the popup is open                |
| `children` | `Snippet`                                  | Autocomplete content                              |
| `...props` | `ComponentProps<typeof Autocomplete.Root>` | All Shards UI Autocomplete props are supported    |

### Autocomplete.Input

The input field component with extended features for size variants and addon support.

| Prop           | Type                        | Default     | Description                                                                            |
| -------------- | --------------------------- | ----------- | -------------------------------------------------------------------------------------- |
| `size`         | `"sm" \| "default" \| "lg"` | `"default"` | The size variant of the input field                                                    |
| `startAddon`   | `Snippet`                   | -           | Content to display at the start of the input, such as an icon                          |
| `showTrigger`  | `boolean`                   | `false`     | Whether to display a trigger button on the right side of the input                     |
| `showClear`    | `boolean`                   | `false`     | Whether to display a clear button on the right side of the input when there is a value |
| `triggerProps` | `AutocompleteTriggerProps`  | -           | Props forwarded to the internal trigger button, useful for overriding `aria-label`     |
| `clearProps`   | `AutocompleteClearProps`    | -           | Props forwarded to the internal clear button, useful for overriding `aria-label`       |
| `class`        | `string`                    | -           | Additional CSS classes to apply to the component                                       |
| `...props`     | `AutocompleteInputProps`    | -           | All standard autocomplete input attributes are supported                               |

### Autocomplete.Popup

The popup container that displays the autocomplete suggestions.

| Prop          | Type                                    | Description                                              |
| ------------- | --------------------------------------- | -------------------------------------------------------- |
| `class`       | `string`                                | Additional CSS classes to apply to the component         |
| `portalProps` | `AutocompletePopupProps["portalProps"]` | Props forwarded to the internal portal                   |
| `...props`    | `AutocompletePopupProps`                | All standard autocomplete popup attributes are supported |

### Autocomplete.List

A scrollable container for autocomplete items.

| Prop       | Type                    | Description                                             |
| ---------- | ----------------------- | ------------------------------------------------------- |
| `class`    | `string`                | Additional CSS classes to apply to the component        |
| `children` | `Snippet`               | List content                                            |
| `...props` | `AutocompleteListProps` | All standard autocomplete list attributes are supported |

### Autocomplete.Item

An individual selectable autocomplete item.

| Prop       | Type                    | Description                                             |
| ---------- | ----------------------- | ------------------------------------------------------- |
| `value`    | `unknown`               | The value of the item                                   |
| `class`    | `string`                | Additional CSS classes to apply to the component        |
| `children` | `Snippet`               | Item content                                            |
| `...props` | `AutocompleteItemProps` | All standard autocomplete item attributes are supported |

### Autocomplete.Empty

Displays a message when no results are found.

| Prop       | Type                     | Description                                              |
| ---------- | ------------------------ | -------------------------------------------------------- |
| `class`    | `string`                 | Additional CSS classes to apply to the component         |
| `children` | `Snippet`                | Empty-state content                                      |
| `...props` | `AutocompleteEmptyProps` | All standard autocomplete empty attributes are supported |

### Autocomplete.Group

Groups related autocomplete items together.

| Prop       | Type                     | Description                                              |
| ---------- | ------------------------ | -------------------------------------------------------- |
| `items`    | `readonly unknown[]`     | The array of items in this group                         |
| `class`    | `string`                 | Additional CSS classes to apply to the component         |
| `children` | `Snippet`                | Group content                                            |
| `...props` | `AutocompleteGroupProps` | All standard autocomplete group attributes are supported |

### Autocomplete.GroupLabel

Displays a label for an autocomplete group.

| Prop       | Type                          | Description                                                    |
| ---------- | ----------------------------- | -------------------------------------------------------------- |
| `class`    | `string`                      | Additional CSS classes to apply to the component               |
| `children` | `Snippet`                     | Label content                                                  |
| `...props` | `AutocompleteGroupLabelProps` | All standard autocomplete group label attributes are supported |

### Autocomplete.Collection

Used to wrap items within a group for rendering.

| Prop       | Type                                             | Description                                                   |
| ---------- | ------------------------------------------------ | ------------------------------------------------------------- |
| `children` | `Snippet<[unknown]>`                             | Renders each filtered item                                    |
| `...props` | `ComponentProps<typeof Autocomplete.Collection>` | All standard autocomplete collection attributes are supported |

## Examples

### Disabled

<ComponentPreview name="p-autocomplete-2" />

### Small Size

<ComponentPreview name="p-autocomplete-3" />

### Large Size

<ComponentPreview name="p-autocomplete-4" />

### With Label

<ComponentPreview name="p-autocomplete-5" />

### Inline Autocomplete

Autofill the input with the highlighted item while navigating with arrow keys.

<ComponentPreview name="p-autocomplete-6" />

### Auto Highlight

Automatically highlight the first matching option.

<ComponentPreview name="p-autocomplete-7" />

### With Clear Button

<ComponentPreview name="p-autocomplete-8" />

### With Trigger and Clear Buttons

<ComponentPreview name="p-autocomplete-9" />

### With Start Addon

Display an icon or other element at the start of the input using the `startAddon` snippet.

<ComponentPreview name="p-autocomplete-14" />

### With Groups

<ComponentPreview name="p-autocomplete-10" />

### With Limit Results

<ComponentPreview name="p-autocomplete-11" />

### Async Search

<ComponentPreview name="p-autocomplete-12" />

### Form Integration

<ComponentPreview name="p-autocomplete-13" />


---

## Document: Avatar

# Avatar

> An image element with a fallback for representing the user.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/avatar)

<ComponentPreview name="p-avatar-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/avatar.json" />

## Usage

```svelte
<script lang="ts">
  import * as Avatar from "$lib/components/ui/avatar/index.js";
</script>

<Avatar.Root>
  <Avatar.Image src="/avatars/01.png" alt="User avatar" />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>
```

## API Reference

### Avatar.Root

Root component. Styled wrapper for `Avatar.Root` from Shards UI with a default size of 32px and rounded-full styling.

### Avatar.Image

Image element for the avatar. Styled wrapper for `Avatar.Image` from Shards UI.

### Avatar.Fallback

Fallback content displayed while the image loads or when it fails. Styled wrapper for `Avatar.Fallback` from Shards UI with a muted background.

See the [Shards Avatar API](https://shardsui.com/svelte/avatar) for image loading callbacks, fallback delay, and primitive props.

## Examples

### Fallback Only

<ComponentPreview name="p-avatar-2" />

### Different Sizes

<ComponentPreview name="p-avatar-3" />

### Different Radius

<ComponentPreview name="p-avatar-4" />

### Group Avatars

<ComponentPreview name="p-avatar-5" />


---

## Document: Badge

# Badge

> A badge or a component that looks like a badge.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/badge)

<ComponentPreview name="p-badge-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/badge.json" />

## Usage

```svelte
<script lang="ts">
  import { Badge } from "$lib/components/ui/badge/index.js";
</script>

<Badge>Badge</Badge>
```

## Link

Use the `as` prop to render another element with the badge styles. Here is a link that looks like a badge.

```svelte
<script lang="ts">
  import { Badge } from "$lib/components/ui/badge/index.js";
</script>

<Badge as="a" href="/pricing">New</Badge>
```

## API Reference

### Badge

A badge component with variant and size options. Native attributes for the selected element pass through.

| Prop      | Type                                                                                                    | Default     | Description                                 |
| --------- | ------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------- |
| `variant` | `"default" \| "destructive" \| "error" \| "info" \| "outline" \| "secondary" \| "success" \| "warning"` | `"default"` | Controls the badge styling and color scheme |
| `size`    | `"default" \| "sm" \| "lg"`                                                                             | `"default"` | Controls the badge size                     |
| `as`      | `keyof SvelteHTMLElements`                                                                              | `"span"`    | Selects the rendered HTML element           |

## Examples

### Outline

<ComponentPreview name="p-badge-2" />

### Secondary

<ComponentPreview name="p-badge-3" />

### Destructive

<ComponentPreview name="p-badge-4" />

### Info

<ComponentPreview name="p-badge-5" />

### Success

<ComponentPreview name="p-badge-6" />

### Warning

<ComponentPreview name="p-badge-7" />

### Error

<ComponentPreview name="p-badge-8" />

### Small

<ComponentPreview name="p-badge-9" />

### Large

<ComponentPreview name="p-badge-10" />

### With Icon

<ComponentPreview name="p-badge-11" />

### With Link

<ComponentPreview name="p-badge-12" />

### With Count

<ComponentPreview name="p-badge-13" />


---

## Document: Breadcrumb

# Breadcrumb

> Displays the path to the current resource using a hierarchy of links.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/breadcrumb)

<ComponentPreview name="p-breadcrumb-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/breadcrumb.json" />

## Usage

```svelte
<script lang="ts">
  import * as Breadcrumb from "$lib/components/ui/breadcrumb/index.js";
</script>

<Breadcrumb.Root>
  <Breadcrumb.List>
    <Breadcrumb.Item><Breadcrumb.Link href="/">Home</Breadcrumb.Link></Breadcrumb.Item>
    <Breadcrumb.Separator />
    <Breadcrumb.Item><Breadcrumb.Ellipsis /></Breadcrumb.Item>
    <Breadcrumb.Item><Breadcrumb.Link href="/docs">Components</Breadcrumb.Link></Breadcrumb.Item>
    <Breadcrumb.Separator />
    <Breadcrumb.Item><Breadcrumb.Page>Breadcrumb</Breadcrumb.Page></Breadcrumb.Item>
  </Breadcrumb.List>
</Breadcrumb.Root>
```

## API Reference

This is a custom Svelte component, not a Shards wrapper.

### Breadcrumb.Root

Root navigation container with `aria-label="breadcrumb"`.

### Breadcrumb.List

Ordered list container for breadcrumb items.

### Breadcrumb.Item

Individual breadcrumb item container.

### Breadcrumb.Link

Link element for navigable breadcrumb items. Use `as` when another native element is required.

| Prop | Type                          | Default | Description              |
| ---- | ----------------------------- | ------- | ------------------------ |
| `as` | `keyof HTMLElementTagNameMap` | `"a"`   | Native element to render |

### Breadcrumb.Page

Non-interactive element representing the current page. Includes `aria-current="page"`.

### Breadcrumb.Separator

Separator between breadcrumb items. Defaults to a Hugeicons chevron and accepts custom children.

### Breadcrumb.Ellipsis

Ellipsis indicator for collapsed breadcrumb items.

## Examples

### With custom separator

<ComponentPreview name="p-breadcrumb-2" />


---

## Document: Button

# Button

> A button or a component that looks like a button.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/button)

<ComponentPreview name="p-button-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/button.json" />

## Usage

```svelte
<script lang="ts">
  import { Button } from "$lib/components/ui/button/index.js";
</script>

<Button>Button</Button>
```

## Link

Pass `href` to render a semantic link with the same styles.

```svelte
<Button href="/login">Login</Button>
```

## API Reference

### Button

A button component with variant, size, and loading states. Native attributes pass to the rendered
element.

| Prop       | Type                                                                                                      | Default     | Description                                                       |
| ---------- | --------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- |
| `variant`  | `"default" \| "destructive" \| "destructive-outline" \| "ghost" \| "link" \| "outline" \| "secondary"`    | `"default"` | Controls the button styling                                       |
| `size`     | `"default" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs" \| "lg" \| "sm" \| "xl" \| "xs"` | `"default"` | Controls the button size                                          |
| `loading`  | `boolean`                                                                                                 | `false`     | Shows a spinner and forces disabled button behavior while loading |
| `href`     | `string`                                                                                                  | —           | Renders a semantic link with the button styles                    |
| `target`   | `string`                                                                                                  | —           | Sets the link browsing context when `href` is present             |
| `rel`      | `string`                                                                                                  | —           | Sets the link relationship when `href` is present                 |
| `download` | `boolean \| string`                                                                                       | —           | Downloads the linked resource when `href` is present              |
| `as`       | `keyof HTMLElementTagNameMap`                                                                             | `"button"`  | Renders a different non-link element                              |

When `loading` is `true`, the component:

- Renders a spinner (`data-slot="button-loading-indicator"`)
- Adds `data-loading` on the button root
- Forces the native `disabled` attribute for buttons
- Sets `aria-disabled="true"`
- Preserves button width because it keeps the child content mounted and hides it visually

See the [Shards Button API](https://shardsui.com/svelte/button) for keyboard and disabled behavior.

## Examples

### Default

<ComponentPreview name="p-button-1" />

### Outline

<ComponentPreview name="p-button-2" />

### Secondary

<ComponentPreview name="p-button-3" />

### Destructive

<ComponentPreview name="p-button-4" />

### Destructive Outline

<ComponentPreview name="p-button-5" />

### Ghost

<ComponentPreview name="p-button-6" />

### Link

<ComponentPreview name="p-button-7" />

### Extra-small Size

<ComponentPreview name="p-button-8" />

### Small Size

<ComponentPreview name="p-button-9" />

### Large Size

<ComponentPreview name="p-button-10" />

### Extra-large Size

<ComponentPreview name="p-button-11" />

### Disabled

<ComponentPreview name="p-button-12" />

### Icon

<ComponentPreview name="p-button-13" />

### Icon Small Size

<ComponentPreview name="p-button-14" />

### Icon Large Size

<ComponentPreview name="p-button-15" />

### With Icon

<ComponentPreview name="p-button-16" />

### With Link

<ComponentPreview name="p-button-17" />

### Loading (Built-in Prop)

<ComponentPreview name="p-button-41" />

### Loading (Custom Composition)

<ComponentPreview name="p-button-18" />


---

## Document: Calendar

# Calendar

> A date picker component with range and multi-select support.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/calendar)

<ComponentPreview name="p-calendar-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/calendar.json" />

## Usage

```svelte
<script lang="ts">
  import { Calendar } from "$lib/components/ui/calendar/index.js";
</script>

<Calendar />
```

## API Reference

`Calendar` is the Svelte calendar implementation used by COSS for Svelte. It preserves the COSS
calendar grid, styling, keyboard navigation, locale handling, and single, multiple, and range
selection contracts.

### Calendar

A calendar component for date selection.

| Prop              | Type                                                             | Default    | Description                                  |
| ----------------- | ---------------------------------------------------------------- | ---------- | -------------------------------------------- |
| `mode`            | `"single" \| "multiple" \| "range"`                              | `"single"` | Selection mode for the calendar.             |
| `captionLayout`   | `"label" \| "dropdown" \| "dropdown-months" \| "dropdown-years"` | `"label"`  | Caption presentation.                        |
| `selected`        | `Date \| Date[] \| DateRange`                                    |            | Current selection. Supports `bind:selected`. |
| `onSelect`        | `(selected, triggerDate, modifiers, event) => void`              |            | Runs after a date selection.                 |
| `showOutsideDays` | `boolean`                                                        | `true`     | Shows dates from adjacent months.            |
| `startMonth`      | `Date`                                                           |            | First navigable month.                       |
| `endMonth`        | `Date`                                                           |            | Last navigable month.                        |
| `classNames`      | `CalendarClassNames`                                             |            | Adds classes to calendar parts.              |
| `components`      | `CalendarComponents`                                             |            | Svelte snippets that replace calendar parts. |

For the full contract, use the exported `CalendarProps` type from
`$lib/components/ui/calendar/index.js`.

### Customizing Cell Size

The calendar uses CSS custom properties for cell sizing. It uses `--spacing(10)` on mobile and
`--spacing(9)` on larger screens by default.

```svelte
<Calendar class="[--cell-size:--spacing(11)] sm:[--cell-size:--spacing(10)]" />
```

## Examples

### Single Date Selection

<ComponentPreview name="p-calendar-2" />

### Date Range Selection

<ComponentPreview name="p-calendar-3" />

### Dropdown Navigation

Use `captionLayout="dropdown"` with `startMonth` and `endMonth` to enable month and year navigation.

<ComponentPreview name="p-calendar-4" />

### Select Dropdown for Month/Year

Calendar with the COSS Select component for month and year navigation.

<ComponentPreview name="p-calendar-5" />

### Combobox Dropdown for Month/Year

Calendar with a searchable COSS Combobox for month and year navigation.

<ComponentPreview name="p-calendar-6" />

## Changelog

- [July 26, 2026](/docs/changelog#react-daypicker-10) — The pinned COSS reference upgraded to
  **React DayPicker 10** and moved from **`react-day-picker`** to **`@daypicker/react`**. This
  Svelte port preserves the resulting COSS behavior and styling without shipping React.


---

## Document: Card

# Card

> A content container for grouping related information.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/card)

<ComponentPreview name="p-card-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/card.json" />

## Usage

```svelte
<script lang="ts">
  import * as Card from "$lib/components/ui/card/index.js";
</script>

<Card.Root>
  <Card.Header>
    <Card.Title>Title</Card.Title>
    <Card.Description>Description</Card.Description>
  </Card.Header>
  <Card.Panel>Content</Card.Panel>
  <Card.Footer>Footer</Card.Footer>
</Card.Root>
```

### Card.Frame with header action

Use `Card.Frame` when you need a framed layout with an action button in the header, such as "Add" or
"Connect":

```svelte
<script lang="ts">
  import Add01Icon from "@hugeicons/core-free-icons/Add01Icon";
  import HugeiconsIcon from "$lib/hugeicons-icon.svelte";
  import { Button } from "$lib/components/ui/button/index.js";
  import * as Card from "$lib/components/ui/card/index.js";
</script>

<Card.Frame>
  <Card.FrameHeader>
    <Card.FrameTitle>Project</Card.FrameTitle>
    <Card.FrameDescription>Manage your project settings and configuration</Card.FrameDescription>
    <Card.FrameAction>
      <Button variant="outline">
        <HugeiconsIcon aria-hidden="true" icon={Add01Icon} strokeWidth={2} />
        Add
      </Button>
    </Card.FrameAction>
  </Card.FrameHeader>
  <Card.Root>
    <Card.Panel>Content</Card.Panel>
  </Card.Root>
</Card.Frame>
```

### Card.Frame with a table

For lists or data grids, render a [Table](/docs/components/table) with `variant="card"` inside
`Card.Frame` so the grid matches the frame's border and radius. See the `Card.Frame` example in the
Table docs. Add the table registry item if it is not already in the project.

## API Reference

This is a custom component using a polymorphic Svelte `as` prop, not a direct Shards UI wrapper.

### Card.Root

Root container for the card. Supports the `as` prop.

| Prop | Type                          | Default | Description                   |
| ---- | ----------------------------- | ------- | ----------------------------- |
| `as` | `keyof HTMLElementTagNameMap` | `"div"` | Render as a different element |

### Card.Header

Header section container. Supports the `as` prop.

### Card.Title

Title text for the card. Supports the `as` prop.

### Card.Description

Description text for the card. Supports the `as` prop.

### Card.Action

Container for action buttons in the header. Automatically positions to the right. Supports the `as` prop.

### Card.Panel

Main content area of the card. Also exported as `Card.Content`. Supports the `as` prop.

### Card.Footer

Footer section for the card. Supports the `as` prop.

## Card.Frame API Reference

`Card.Frame` is an alternative layout for cards that groups a header, content, and footer with consistent styling and clipping. Use it when you need a framed card with optional header actions.

### Card.Frame

Root container for the framed card layout. Supports the `as` prop.

### Card.FrameHeader

Header section for the frame. Contains title, description, and optionally `Card.FrameAction`. Supports the `as` prop.

### Card.FrameTitle

Title text for the frame. Supports the `as` prop.

### Card.FrameDescription

Description text for the frame. Supports the `as` prop.

### Card.FrameAction

Container for action buttons (e.g. "Add", "Edit") in the header. Place it as a sibling of `Card.FrameTitle` and `Card.FrameDescription` inside `Card.FrameHeader`. It is positioned in the top-right via CSS grid (`col-start-2`, `row-span-2`, `self-center`, `justify-self-end`). Use it for primary actions that apply to the entire frame. Supports the `as` prop.

### Card.FrameFooter

Footer section for the frame. Supports the `as` prop.


---

## Document: Checkbox

# Checkbox

> A control allowing the user to toggle between checked and not checked.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/checkbox)

<ComponentPreview name="p-checkbox-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/checkbox.json" />

## Usage

```svelte
<script lang="ts">
  import { Checkbox } from "$lib/components/ui/checkbox/index.js";
</script>

<Checkbox aria-label="Accept terms" />
```

## API Reference

### Checkbox

`Checkbox` includes the COSS check and indeterminate indicators. Use `checked` for an initial value
or `bind:checked` for controlled state. Native form props and `onCheckedChange` pass to the Shards
root.

See the [Shards Checkbox API](https://shardsui.com/svelte/checkbox) for form, validation, and state
props.

## Examples

For accessible labelling and validation, prefer using the `Field` component to wrap checkboxes. See the related example: [Checkbox field](/docs/components/field#checkbox-field).

### Disabled

<ComponentPreview name="p-checkbox-2" />

### With Description

<ComponentPreview name="p-checkbox-3" />

### Card Style

<ComponentPreview name="p-checkbox-4" />

### Form Integration

Field provides accessible labelling and validation primitives for form controls. Use it with `Form` to submit values.

<ComponentPreview name="p-checkbox-5" />


---

## Document: Checkbox Group

# Checkbox Group

> Provides shared state to a series of checkboxes.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/checkbox-group)

<ComponentPreview name="p-checkbox-group-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/checkbox-group.json" />

## Usage

```svelte
<script lang="ts">
  import { Label } from "$lib/components/ui/label/index.js";
  import * as CheckboxGroup from "$lib/components/ui/checkbox-group/index.js";
</script>

<CheckboxGroup.Root aria-label="Select frameworks" defaultValue={["next"]}>
  <Label><CheckboxGroup.Item value="next" /> Next.js</Label>
  <Label><CheckboxGroup.Item value="vite" /> Vite</Label>
  <Label><CheckboxGroup.Item value="astro" /> Astro</Label>
</CheckboxGroup.Root>
```

## API Reference

### CheckboxGroup.Root

The root owns an array of selected values. Use `defaultValue` for the initial selection or
`bind:value` for controlled state. `allValues` enables parent-checkbox selection.

### CheckboxGroup.Item

An item registers its `value` with the root and shares disabled and form state. The public
`CheckboxGroup.Checkbox` alias points to the same part.

See the [Shards Checkbox Group API](https://shardsui.com/svelte/checkbox-group) for parent selection,
form values, and validation.

## Examples

For accessible group labelling and validation, prefer wrapping checkbox groups with `Field` and `Fieldset`. See the related example: [Checkbox group field](/docs/components/field#checkbox-group-field).

### With Disabled Item

<ComponentPreview name="p-checkbox-group-2" />

### Parent Checkbox

<ComponentPreview name="p-checkbox-group-3" />

### Nested Parent Checkbox

<ComponentPreview name="p-checkbox-group-4" />

### Form Integration

<ComponentPreview name="p-checkbox-group-5" />


---

## Document: Collapsible

# Collapsible

> A collapsible panel controlled by a button trigger.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/collapsible)

<ComponentPreview name="p-collapsible-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/collapsible.json" />

## Usage

```svelte
<script lang="ts">
  import * as Collapsible from "$lib/components/ui/collapsible/index.js";
</script>

<Collapsible.Root>
  <Collapsible.Trigger>Can I access the file in the cloud?</Collapsible.Trigger>
  <Collapsible.Panel>Yes, you can access the file in the cloud.</Collapsible.Panel>
</Collapsible.Root>
```

## API Reference

### Collapsible.Root

The root component owns the open state. Use `open` and `bind:open` for controlled state, or
`defaultOpen` for the initial uncontrolled state.

### Collapsible.Trigger

The button that toggles the panel. Its `delegate` snippet can merge Collapsible behavior into a
styled button without adding another DOM element.

### Collapsible.Panel

The collapsible content panel. It uses Shards mounting, ARIA relationships, measurements, and
transition state with the COSS height animation. `Collapsible.Content` is an alias.

See the [Shards Collapsible API](https://shardsui.com/svelte/collapsible) for the complete primitive
contract.


---

## Document: Combobox

# Combobox

> An input combined with a list of predefined items to select.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/combobox)

<ComponentPreview name="p-combobox-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/combobox.json" />

## Usage

### Single Selection

```svelte
<script lang="ts">
  import * as Combobox from "$lib/components/ui/combobox/index.js";
</script>
```

```svelte
<script lang="ts">
  const items = [
    { value: "apple", label: "Apple" },
    { value: "banana", label: "Banana" },
    { value: "orange", label: "Orange" },
    { value: "grape", label: "Grape" },
  ];
</script>

<Combobox.Root {items}>
  <Combobox.Input placeholder="Select an item..." />
  <Combobox.Popup>
    <Combobox.Empty>No results found.</Combobox.Empty>
    <Combobox.List>
      <Combobox.Collection>
        {#snippet children(item)}
          <Combobox.Item value={item}>{item.label}</Combobox.Item>
        {/snippet}
      </Combobox.Collection>
    </Combobox.List>
  </Combobox.Popup>
</Combobox.Root>
```

### Multiple Selection

```svelte
<script lang="ts">
  import * as Combobox from "$lib/components/ui/combobox/index.js";
</script>
```

```svelte
<script lang="ts">
  const items = [
    { value: "apple", label: "Apple" },
    { value: "banana", label: "Banana" },
    { value: "orange", label: "Orange" },
    { value: "grape", label: "Grape" },
  ] as const;
  type Item = (typeof items)[number];
</script>

<Combobox.Root {items} multiple>
  <Combobox.Chips>
    <Combobox.Value>
      {#snippet children(value: Item[])}
        {#each value as item (item.value)}
          <Combobox.Chip aria-label={item.value} value={item.value}>
            {item.label}
          </Combobox.Chip>
        {/each}
        <Combobox.ChipsInput
          aria-label="Select an item"
          placeholder={value.length > 0 ? undefined : "Select an item..."}
        />
      {/snippet}
    </Combobox.Value>
  </Combobox.Chips>
  <Combobox.Popup>
    <Combobox.Empty>No results found.</Combobox.Empty>
    <Combobox.List>
      <Combobox.Collection>
        {#snippet children(item: Item)}
          <Combobox.Item value={item}>{item.label}</Combobox.Item>
        {/snippet}
      </Combobox.Collection>
    </Combobox.List>
  </Combobox.Popup>
</Combobox.Root>
```

## API Reference

### Combobox.Root

The root combobox component. Manages the combobox state and provides context to child components.

| Prop       | Type                 | Description                                   |
| ---------- | -------------------- | --------------------------------------------- |
| `items`    | `readonly unknown[]` | The array of items to display in the combobox |
| `multiple` | `boolean`            | Whether to allow multiple selection           |
| `open`     | `boolean`            | Controls whether the popup is open            |
| `children` | `Snippet`            | Combobox content                              |
| `...props` | `ComboboxRootProps`  | All Shards UI Combobox props are supported    |

### Combobox.Input

The input field component for single selection mode with extended features for size variants and addon support.

| Prop           | Type                        | Default     | Description                                                                            |
| -------------- | --------------------------- | ----------- | -------------------------------------------------------------------------------------- |
| `size`         | `"sm" \| "default" \| "lg"` | `"default"` | The size variant of the input field                                                    |
| `startAddon`   | `Snippet`                   | -           | Content to display at the start of the input, such as an icon                          |
| `showTrigger`  | `boolean`                   | `true`      | Whether to display a trigger button on the right side of the input                     |
| `showClear`    | `boolean`                   | `false`     | Whether to display a clear button on the right side of the input when there is a value |
| `triggerProps` | `ComboboxTriggerProps`      | -           | Props forwarded to the internal trigger button, useful for overriding `aria-label`     |
| `clearProps`   | `ComboboxClearProps`        | -           | Props forwarded to the internal clear button, useful for overriding `aria-label`       |
| `class`        | `string`                    | -           | Additional CSS classes to apply to the component                                       |
| `...props`     | `ComboboxInputProps`        | -           | All standard combobox input attributes are supported                                   |

### Combobox.Popup

The popup container that displays the combobox options.

| Prop          | Type                                | Description                                          |
| ------------- | ----------------------------------- | ---------------------------------------------------- |
| `class`       | `string`                            | Additional CSS classes to apply to the component     |
| `portalProps` | `ComboboxPopupProps["portalProps"]` | Props forwarded to the internal portal               |
| `...props`    | `ComboboxPopupProps`                | All standard combobox popup attributes are supported |

### Combobox.List

A scrollable container for combobox items.

| Prop       | Type                | Description                                         |
| ---------- | ------------------- | --------------------------------------------------- |
| `class`    | `string`            | Additional CSS classes to apply to the component    |
| `children` | `Snippet`           | List content                                        |
| `...props` | `ComboboxListProps` | All standard combobox list attributes are supported |

### Combobox.Item

An individual selectable combobox item.

| Prop       | Type                | Description                                         |
| ---------- | ------------------- | --------------------------------------------------- |
| `value`    | `unknown`           | The value of the item                               |
| `class`    | `string`            | Additional CSS classes to apply to the component    |
| `children` | `Snippet`           | Item content                                        |
| `...props` | `ComboboxItemProps` | All standard combobox item attributes are supported |

### Combobox.Empty

Displays a message when no results are found.

| Prop       | Type                 | Description                                          |
| ---------- | -------------------- | ---------------------------------------------------- |
| `class`    | `string`             | Additional CSS classes to apply to the component     |
| `children` | `Snippet`            | Empty-state content                                  |
| `...props` | `ComboboxEmptyProps` | All standard combobox empty attributes are supported |

### Combobox.Group

Groups related combobox items together.

| Prop       | Type                 | Description                                          |
| ---------- | -------------------- | ---------------------------------------------------- |
| `items`    | `readonly unknown[]` | The array of items in this group                     |
| `class`    | `string`             | Additional CSS classes to apply to the component     |
| `children` | `Snippet`            | Group content                                        |
| `...props` | `ComboboxGroupProps` | All standard combobox group attributes are supported |

### Combobox.GroupLabel

Displays a label for a combobox group.

| Prop       | Type                      | Description                                                |
| ---------- | ------------------------- | ---------------------------------------------------------- |
| `class`    | `string`                  | Additional CSS classes to apply to the component           |
| `children` | `Snippet`                 | Label content                                              |
| `...props` | `ComboboxGroupLabelProps` | All standard combobox group label attributes are supported |

### Combobox.Collection

Used to wrap items within a group for rendering.

| Prop       | Type                                         | Description                                               |
| ---------- | -------------------------------------------- | --------------------------------------------------------- |
| `children` | `Snippet<[unknown]>`                         | Renders each filtered item                                |
| `...props` | `ComponentProps<typeof Combobox.Collection>` | All standard combobox collection attributes are supported |

### Combobox.Chips

Container for displaying selected chips in multiple selection mode.

| Prop         | Type                 | Description                                       |
| ------------ | -------------------- | ------------------------------------------------- |
| `startAddon` | `Snippet`            | Content to display at the start of the chips area |
| `class`      | `string`             | Additional CSS classes to apply to the component  |
| `children`   | `Snippet`            | Chips content                                     |
| `...props`   | `ComboboxChipsProps` | All standard div attributes are supported         |

### Combobox.ChipsInput

The input field component for use inside `Combobox.Chips` in multiple selection mode. This is a minimal input without the wrapper, trigger, or clear button.

| Prop       | Type                        | Default     | Description                                          |
| ---------- | --------------------------- | ----------- | ---------------------------------------------------- |
| `size`     | `"sm" \| "default" \| "lg"` | `"default"` | The size variant of the input field                  |
| `class`    | `string`                    | -           | Additional CSS classes to apply to the component     |
| `...props` | `ComboboxChipsInputProps`   | -           | All standard combobox input attributes are supported |

### Combobox.Chip

An individual chip representing a selected item in multiple selection mode.

| Prop          | Type                      | Description                                                                       |
| ------------- | ------------------------- | --------------------------------------------------------------------------------- |
| `removeProps` | `ComboboxChipRemoveProps` | Props forwarded to the internal remove button, useful for overriding `aria-label` |
| `class`       | `string`                  | Additional CSS classes to apply to the component                                  |
| `children`    | `Snippet`                 | Chip content                                                                      |
| `...props`    | `ComboboxChipProps`       | All standard combobox chip attributes are supported                               |

### Combobox.Value

Provides access to the current value for custom rendering.

| Prop       | Type                 | Description                                          |
| ---------- | -------------------- | ---------------------------------------------------- |
| `children` | `Snippet<[unknown]>` | Receives the current combobox value                  |
| `...props` | `ComboboxValueProps` | All standard combobox value attributes are supported |

## Examples

### Disabled

<ComponentPreview name="p-combobox-2" />

### Small Size

<ComponentPreview name="p-combobox-3" />

### Large Size

<ComponentPreview name="p-combobox-4" />

### With Label

<ComponentPreview name="p-combobox-5" />

### Auto Highlight

Automatically highlight the first matching option.

<ComponentPreview name="p-combobox-6" />

### With Clear Button

<ComponentPreview name="p-combobox-7" />

### With Groups

<ComponentPreview name="p-combobox-8" />

### With Multiple Selection

<ComponentPreview name="p-combobox-9" />

### With Start Addon

Display an icon or other element at the start of the input using the `startAddon` prop.

<ComponentPreview name="p-combobox-13" />

### With Start Addon - Multiple

Use the `startAddon` prop on `Combobox.Chips` to display an icon at the start when using multiple selection.

<ComponentPreview name="p-combobox-14" />

### With Input Inside Popup

<ComponentPreview name="p-combobox-10" />

### With Select-like Button

Use `selectTriggerClass` on `Combobox.Trigger` to make the combobox trigger look like a select.

<ComponentPreview name="p-combobox-18" />

### Form Integration

<ComponentPreview name="p-combobox-11" />

### Form Integration - Multiple

<ComponentPreview name="p-combobox-12" />


---

## Document: Command

# Command

> A command palette component built with Dialog and Autocomplete for searching and executing commands.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/command)

<ComponentPreview name="p-command-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/command.json" />

## Usage

```svelte
<script lang="ts">
  import * as Command from "$lib/components/ui/command/index.js";
  import { buttonVariants } from "$lib/components/ui/button/index.js";
</script>
```

```svelte
<script lang="ts">
  const items = [
    { value: "linear", label: "Linear" },
    { value: "figma", label: "Figma" },
    { value: "slack", label: "Slack" },
  ];
</script>

<Command.DialogRoot>
  <Command.DialogTrigger class={buttonVariants({ variant: "outline" })}>
    Open Command Palette
  </Command.DialogTrigger>

  <Command.DialogPopup aria-label="Command palette">
    <Command.Root {items}>
      <Command.Input placeholder="Search..." />
      <Command.Empty>No results found.</Command.Empty>
      <Command.List>
        <Command.Collection>
          {#snippet children(item)}
            <Command.Item value={item}>{item.label}</Command.Item>
          {/snippet}
        </Command.Collection>
      </Command.List>
    </Command.Root>
  </Command.DialogPopup>
</Command.DialogRoot>
```

## API Reference

### Command.Root

The root component that wraps the autocomplete functionality. It's an alias for `Autocomplete.Root` with sensible defaults for command palette behavior: `autoHighlight="always"`, `keepHighlight={true}`, and `open={true}`.

| Prop            | Type                  | Default    | Description                                  |
| --------------- | --------------------- | ---------- | -------------------------------------------- |
| `items`         | `readonly unknown[]`  | -          | The array of items to display in the command |
| `open`          | `boolean`             | `true`     | Controls whether the command is open         |
| `autoHighlight` | `boolean \| "always"` | `"always"` | Controls automatic highlighting of items     |
| `keepHighlight` | `boolean`             | `true`     | Whether to maintain highlight state          |
| `children`      | `Snippet`             | -          | Command content                              |
| `...props`      | `CommandRootProps`    | -          | All Shards Autocomplete props are supported  |

### Command.DialogRoot

A wrapper component that provides the dialog root functionality. It's an alias for `Dialog.Root` from Shards UI.

| Prop           | Type                                           | Description                             |
| -------------- | ---------------------------------------------- | --------------------------------------- |
| `open`         | `boolean`                                      | Controls whether the dialog is open     |
| `onOpenChange` | `(open: boolean) => void`                      | Called when the open state changes      |
| `children`     | `Snippet<[{ payload: Payload \| undefined }]>` | Dialog content                          |
| `...props`     | `ComponentProps<typeof Command.DialogRoot>`    | All standard dialog props are supported |

### Command.DialogTrigger

The trigger button that opens the command dialog. Renders as a button by default.

| Prop       | Type                          | Description                                          |
| ---------- | ----------------------------- | ---------------------------------------------------- |
| `as`       | `keyof HTMLElementTagNameMap` | Element to render                                    |
| `class`    | `string`                      | Additional CSS classes to apply to the component     |
| `children` | `Snippet`                     | Trigger content                                      |
| `...props` | `CommandDialogTriggerProps`   | All standard dialog trigger attributes are supported |

### Command.DialogPopup

The popup content container that displays the command palette inside a dialog.

| Prop          | Type                                     | Description                                        |
| ------------- | ---------------------------------------- | -------------------------------------------------- |
| `class`       | `string`                                 | Additional CSS classes to apply to the component   |
| `portalProps` | `CommandDialogPopupProps["portalProps"]` | Props forwarded to the internal portal             |
| `children`    | `CommandDialogPopupProps["children"]`    | Popup content                                      |
| `...props`    | `CommandDialogPopupProps`                | All standard dialog popup attributes are supported |

### Command.Input

The search input field with an integrated search icon. Automatically includes a search icon via `startAddon` and is sized to `lg` by default.

| Prop          | Type                | Description                                              |
| ------------- | ------------------- | -------------------------------------------------------- |
| `placeholder` | `string`            | The placeholder text for the input                       |
| `class`       | `string`            | Additional CSS classes to apply to the component         |
| `startAddon`  | `Snippet`           | Replaces the integrated search icon                      |
| `...props`    | `CommandInputProps` | All standard autocomplete input attributes are supported |

### Command.List

A scrollable container for command items. It wraps `Autocomplete.List` with scroll functionality.

| Prop       | Type               | Description                                             |
| ---------- | ------------------ | ------------------------------------------------------- |
| `class`    | `string`           | Additional CSS classes to apply to the component        |
| `children` | `Snippet`          | List content                                            |
| `...props` | `CommandListProps` | All standard autocomplete list attributes are supported |

### Command.Panel

A container component that provides styling for command content outside of dialogs. Useful when building standalone command interfaces with a bordered, elevated appearance.

| Prop       | Type                | Description                                      |
| ---------- | ------------------- | ------------------------------------------------ |
| `as`       | `"div" \| "kbd"`    | Element to render                                |
| `class`    | `string`            | Additional CSS classes to apply to the component |
| `children` | `Snippet`           | Panel content                                    |
| `...props` | `CommandPanelProps` | All standard element attributes are supported    |

### Command.Empty

Displays a message when no results are found.

| Prop       | Type                | Description                                              |
| ---------- | ------------------- | -------------------------------------------------------- |
| `class`    | `string`            | Additional CSS classes to apply to the component         |
| `children` | `Snippet`           | Empty-state content                                      |
| `...props` | `CommandEmptyProps` | All standard autocomplete empty attributes are supported |

### Command.Group

Groups related command items together. Wraps `Autocomplete.Group`.

| Prop       | Type                 | Description                                              |
| ---------- | -------------------- | -------------------------------------------------------- |
| `items`    | `readonly unknown[]` | The array of items in this group                         |
| `class`    | `string`             | Additional CSS classes to apply to the component         |
| `children` | `Snippet`            | Group content                                            |
| `...props` | `CommandGroupProps`  | All standard autocomplete group attributes are supported |

### Command.GroupLabel

Displays a label for a command group.

| Prop       | Type                     | Description                                                    |
| ---------- | ------------------------ | -------------------------------------------------------------- |
| `class`    | `string`                 | Additional CSS classes to apply to the component               |
| `children` | `Snippet`                | Label content                                                  |
| `...props` | `CommandGroupLabelProps` | All standard autocomplete group label attributes are supported |

### Command.Item

An individual selectable command item. Extends `Autocomplete.Item`.

| Prop       | Type               | Description                                             |
| ---------- | ------------------ | ------------------------------------------------------- |
| `value`    | `unknown`          | The value of the item                                   |
| `class`    | `string`           | Additional CSS classes to apply to the component        |
| `children` | `Snippet`          | Item content                                            |
| `...props` | `CommandItemProps` | All standard autocomplete item attributes are supported |

### Command.Separator

A visual separator between command groups or items. Includes default vertical spacing with the `my-2` class.

| Prop       | Type                    | Description                                                  |
| ---------- | ----------------------- | ------------------------------------------------------------ |
| `class`    | `string`                | Additional CSS classes to apply to the component             |
| `...props` | `CommandSeparatorProps` | All standard autocomplete separator attributes are supported |

### Command.Shortcut

Displays keyboard shortcuts in a styled `kbd` element.

| Prop       | Type                   | Description                                      |
| ---------- | ---------------------- | ------------------------------------------------ |
| `class`    | `string`               | Additional CSS classes to apply to the component |
| `children` | `Snippet`              | Shortcut text                                    |
| `...props` | `CommandShortcutProps` | All standard element attributes are supported    |

### Command.Footer

A footer section for displaying hints or additional keyboard shortcuts. Renders as a styled `div` with padding and border.

| Prop       | Type                 | Description                                      |
| ---------- | -------------------- | ------------------------------------------------ |
| `class`    | `string`             | Additional CSS classes to apply to the component |
| `children` | `Snippet`            | Footer content                                   |
| `...props` | `CommandFooterProps` | All standard element attributes are supported    |

### Command.Collection

Used within `Command.Group` to wrap items when using grouped data. It's an alias for `Autocomplete.Collection` from the Autocomplete component.

| Prop       | Type                                        | Description                                                   |
| ---------- | ------------------------------------------- | ------------------------------------------------------------- |
| `children` | `Snippet<[unknown]>`                        | Renders each filtered item                                    |
| `...props` | `ComponentProps<typeof Command.Collection>` | All standard autocomplete collection attributes are supported |

## Examples

### With Keyboard Shortcut

You can add a keyboard shortcut to open the command palette:

```svelte
<script lang="ts">
  let open = $state(false);

  function down(event: KeyboardEvent) {
    if (event.key === "k" && (event.metaKey || event.ctrlKey)) {
      event.preventDefault();
      open = !open;
    }
  }

  $effect(() => {
    document.addEventListener("keydown", down);
    return () => document.removeEventListener("keydown", down);
  });
</script>

<Command.DialogRoot bind:open>...</Command.DialogRoot>
```

### With Grouped Items

```svelte
<script lang="ts">
  const groupedItems = [
    {
      value: "Suggestions",
      items: [
        { value: "linear", label: "Linear" },
        { value: "figma", label: "Figma" },
      ],
    },
    {
      value: "Commands",
      items: [
        { value: "clipboard", label: "Clipboard History" },
        { value: "settings", label: "System Preferences" },
      ],
    },
  ];
</script>

<Command.Root items={groupedItems}>
  <Command.Input placeholder="Search..." />
  <Command.Empty>No results found.</Command.Empty>
  <Command.List>
    <Command.Collection>
      {#snippet children(group)}
        <Command.Group items={group.items}>
          <Command.GroupLabel>{group.value}</Command.GroupLabel>
          <Command.Collection>
            {#snippet children(item)}
              <Command.Item value={item.value}>{item.label}</Command.Item>
            {/snippet}
          </Command.Collection>
        </Command.Group>
        <Command.Separator />
      {/snippet}
    </Command.Collection>
  </Command.List>
</Command.Root>
```

### Standalone Command (Without Dialog)

You can use the Command component without a dialog wrapper:

```svelte
<Command.Root open {items}>
  <Command.Input placeholder="Type a command..." />
  <Command.Empty>No results found.</Command.Empty>
  <Command.List>
    <Command.Collection>
      {#snippet children(item)}
        <Command.Item value={item.value}>{item.label}</Command.Item>
      {/snippet}
    </Command.Collection>
  </Command.List>
</Command.Root>
```


---

## Document: Context Menu

# Context Menu

> A menu that appears at the pointer on right click or long press.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/context-menu)

<ComponentPreview name="p-context-menu-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/context-menu.json" />

## Usage

```svelte
<script lang="ts">
  import * as ContextMenu from "$lib/components/ui/context-menu/index.js";
</script>

<ContextMenu.Root>
  <ContextMenu.Trigger>Right click here</ContextMenu.Trigger>
  <ContextMenu.Popup>
    <ContextMenu.Item>Back</ContextMenu.Item>
    <ContextMenu.Item>Forward</ContextMenu.Item>
    <ContextMenu.Separator />
    <ContextMenu.LinkItem href="/docs">Documentation</ContextMenu.LinkItem>
    <ContextMenu.Separator />
    <ContextMenu.Sub>
      <ContextMenu.SubTrigger>More tools</ContextMenu.SubTrigger>
      <ContextMenu.SubPopup>
        <ContextMenu.Item>Inspect</ContextMenu.Item>
        <ContextMenu.Item>View source</ContextMenu.Item>
      </ContextMenu.SubPopup>
    </ContextMenu.Sub>
  </ContextMenu.Popup>
</ContextMenu.Root>
```

## API Reference

### ContextMenu.Root

Root component. Alias for `ContextMenu.Root` from Shards UI.

### ContextMenu.Trigger

An area that opens the menu on right click or long press. Renders a `<div>` element.

### ContextMenu.Popup

Popup container that displays the menu content at the pointer.

| Prop          | Type                                     | Default    | Description                              |
| ------------- | ---------------------------------------- | ---------- | ---------------------------------------- |
| `side`        | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Side of the anchor to position the popup |
| `align`       | `"start" \| "center" \| "end"`           | `"center"` | Alignment relative to the anchor         |
| `sideOffset`  | `number`                                 | `4`        | Distance from the anchor in pixels       |
| `alignOffset` | `number`                                 | -          | Offset along the alignment axis          |
| `portalProps` | `ContextMenuPopupProps["portalProps"]`   | -          | Props forwarded to the internal portal   |

### ContextMenu.Group

Groups related menu items. Alias for `ContextMenu.Group` from Shards UI.

### ContextMenu.Item

Individual menu item.

| Prop      | Type                         | Default     | Description                                           |
| --------- | ---------------------------- | ----------- | ----------------------------------------------------- |
| `inset`   | `boolean`                    | -           | Adds left padding to align with items that have icons |
| `variant` | `"default" \| "destructive"` | `"default"` | Controls the item styling                             |

**Using `inset`:** When mixing items with and without icons, use `inset` on icon-less items to maintain alignment:

```svelte
<ContextMenu.Item><PencilIcon /> Edit</ContextMenu.Item>
<ContextMenu.Item inset>Properties</ContextMenu.Item>
```

### ContextMenu.LinkItem

Link menu item for navigation. **`LinkItem`** renders a native **`<a>`** when you pass **`href`**. Styled like **`ContextMenu.Item`**.

| Prop           | Type                         | Default     | Description                                           |
| -------------- | ---------------------------- | ----------- | ----------------------------------------------------- |
| `inset`        | `boolean`                    | -           | Adds left padding to align with items that have icons |
| `variant`      | `"default" \| "destructive"` | `"default"` | Controls the item styling                             |
| `closeOnClick` | `boolean`                    | `true`      | Whether the menu closes when the link is clicked      |

Use **`href`** for plain anchor links:

```svelte
<ContextMenu.LinkItem href="/docs">Docs</ContextMenu.LinkItem>
```

### ContextMenu.CheckboxItem

Checkbox menu item.

| Prop      | Type                    | Default     | Description                                             |
| --------- | ----------------------- | ----------- | ------------------------------------------------------- |
| `variant` | `"default" \| "switch"` | `"default"` | Display style; `switch` shows a toggle switch indicator |

### ContextMenu.RadioGroup

Groups radio menu items. Alias for `ContextMenu.RadioGroup` from Shards UI.

### ContextMenu.RadioItem

Radio menu item. Styled wrapper for `ContextMenu.RadioItem` from Shards UI.

### ContextMenu.GroupLabel

Label for a menu group.

| Prop    | Type      | Default | Description                                           |
| ------- | --------- | ------- | ----------------------------------------------------- |
| `inset` | `boolean` | -       | Adds left padding to align with items that have icons |

### ContextMenu.Separator

Visual separator between menu items.

### ContextMenu.Shortcut

Displays keyboard shortcut text. Custom component.

### ContextMenu.Sub

Submenu container. Alias for `ContextMenu.Sub` from Shards UI.

### ContextMenu.SubTrigger

Trigger for opening a submenu.

| Prop    | Type      | Default | Description                                           |
| ------- | --------- | ------- | ----------------------------------------------------- |
| `inset` | `boolean` | -       | Adds left padding to align with items that have icons |

### ContextMenu.SubPopup

Popup for submenu content.

| Prop          | Type                           | Default   | Description                                                               |
| ------------- | ------------------------------ | --------- | ------------------------------------------------------------------------- |
| `align`       | `"start" \| "center" \| "end"` | `"start"` | Alignment relative to the trigger                                         |
| `sideOffset`  | `number`                       | `0`       | Distance from the trigger in pixels                                       |
| `alignOffset` | `number`                       | `-5`      | Offset along the alignment axis; defaults to `-5` unless `align="center"` |

## Examples

### With Link

<ComponentPreview name="p-context-menu-2" />

### Nested Menu

<ComponentPreview name="p-context-menu-3" />

### With Checkbox

<ComponentPreview name="p-context-menu-4" />

### With Group Label

<ComponentPreview name="p-context-menu-5" />

### With Icons

<ComponentPreview name="p-context-menu-6" />

### With Radio Group

<ComponentPreview name="p-context-menu-7" />

### With Switch

`ContextMenu.CheckboxItem` supports a `variant="switch"` prop that displays a decorative switch indicator instead of a checkmark. This is a purely visual variant — the component remains a checkbox item with the same functionality.

<ComponentPreview name="p-context-menu-8" />


---

## Document: Date Picker

# Date Picker

> A date picker component built with Calendar and Popover.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/date-picker)

<ComponentPreview name="p-date-picker-1" />

## About

The Date Picker is built using a composition of the `Calendar` and `Popover` components.

## Installation

The Date Picker is a composition pattern, not a standalone component. Install the required components:

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/calendar.json https://coss-sv.vercel.app/r/popover.json https://coss-sv.vercel.app/r/button.json" />

## Usage

```svelte
<script lang="ts">
  import { buttonVariants } from "$lib/components/ui/button/index.js";
  import { Calendar } from "$lib/components/ui/calendar/index.js";
  import * as Popover from "$lib/components/ui/popover/index.js";
  import HugeiconsIcon from "$lib/hugeicons-icon.svelte";
  import Calendar03Icon from "@hugeicons/core-free-icons/Calendar03Icon";

  let date = $state<Date>();
</script>

<Popover.Root>
  <Popover.Trigger class={buttonVariants({ class: "w-[280px] justify-start", variant: "outline" })}>
    <HugeiconsIcon aria-hidden="true" icon={Calendar03Icon} strokeWidth={2} />
    {date ? date.toLocaleDateString() : "Pick a date"}
  </Popover.Trigger>
  <Popover.Popup align="start" class="w-auto p-0">
    <Calendar mode="single" bind:selected={date} />
  </Popover.Popup>
</Popover.Root>
```

## Examples

### Date Range Picker

<ComponentPreview name="p-date-picker-2" />

### With Dropdown Navigation

Use `captionLayout="dropdown"` for date of birth or historical date selection.

<ComponentPreview name="p-date-picker-3" />

### With Presets

<ComponentPreview name="p-date-picker-4" />

### With Input

<ComponentPreview name="p-date-picker-5" />

### Close on Select

Control the popover state to close it when a date is selected.

<ComponentPreview name="p-date-picker-6" />


---

## Document: Dialog

# Dialog

> A popup that opens on top of the entire page.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/dialog)

<ComponentPreview name="p-dialog-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/dialog.json" />

## Usage

```svelte
<script lang="ts">
  import * as Dialog from "$lib/components/ui/dialog/index.js";
</script>

<Dialog.Root>
  <Dialog.Trigger>Open Dialog</Dialog.Trigger>
  <Dialog.Popup>
    <Dialog.Header>
      <Dialog.Title>Dialog Title</Dialog.Title>
      <Dialog.Description>Dialog Description</Dialog.Description>
    </Dialog.Header>
    <Dialog.Panel>Content</Dialog.Panel>
    <Dialog.Footer>
      <Dialog.Close>Close</Dialog.Close>
    </Dialog.Footer>
  </Dialog.Popup>
</Dialog.Root>
```

## API Reference

### Dialog.Root

Root component. Wraps `Dialog.Root` from Shards UI.

### Dialog.Trigger

Trigger button that opens the dialog. Wraps `Dialog.Trigger` from Shards UI.

### Dialog.createHandle

Creates a handle for detached dialog triggers. Use it when the trigger and popup need to be coordinated across different parts of the tree.

### Dialog.Popup

Popup container that displays the dialog content. Also exported as `Dialog.Content`.

| Prop                  | Type                                   | Default | Description                                                                                                    |
| --------------------- | -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `showCloseButton`     | `boolean`                              | `true`  | When true, displays a close button in the top-right corner                                                     |
| `bottomStickOnMobile` | `boolean`                              | `true`  | When true, sticks to the bottom of the screen on mobile devices                                                |
| `closeProps`          | `ComponentProps<typeof Dialog.Close>`  | -       | Props forwarded to the internal close button, useful for overriding `aria-label`                               |
| `portalProps`         | `ComponentProps<typeof Dialog.Portal>` | -       | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see the Shards UI Dialog portal API |

### Dialog.Header

Container for the dialog title and description. Supports the `as` prop for polymorphic composition (for example, `as="header"`).

### Dialog.Footer

Footer section for action buttons. Supports the `as` prop for polymorphic composition.

| Prop      | Type                  | Default     | Description                                                                                |
| --------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `variant` | `"default" \| "bare"` | `"default"` | Controls the footer styling. `default` includes border and background, `bare` removes them |

**Example:**

```svelte
<!-- Default variant (with border and background) -->
<Dialog.Footer>
  <Dialog.Close>Cancel</Dialog.Close>
  <Button>Save</Button>
</Dialog.Footer>

<!-- Bare variant (no border or background) -->
<Dialog.Footer variant="bare">
  <Dialog.Close>Cancel</Dialog.Close>
  <Button>Save</Button>
</Dialog.Footer>
```

### Dialog.Title

Title component. Wraps `Dialog.Title` from Shards UI.

### Dialog.Description

Description component. Wraps `Dialog.Description` from Shards UI.

### Dialog.Panel

Scrollable content container. Automatically wraps content in a `ScrollArea` component. Supports the `as` prop for polymorphic composition.

| Prop         | Type      | Default | Description                                    |
| ------------ | --------- | ------- | ---------------------------------------------- |
| `scrollFade` | `boolean` | `true`  | When true, shows a fade effect at scroll edges |

**Example:**

```svelte
<Dialog.Panel>
  <!-- Long content that will scroll if it exceeds the dialog height -->
  <div>...</div>
</Dialog.Panel>
```

### Dialog.Close

Close button component. Wraps `Dialog.Close` from Shards UI.

### Dialog.Portal

Portal component for rendering outside the DOM hierarchy. Wraps `Dialog.Portal` from Shards UI.

### Dialog.Backdrop

Backdrop/overlay component. Also exported as `Dialog.Overlay`. Wraps `Dialog.Backdrop` from Shards UI.

### Dialog.Viewport

Viewport component for positioning. Wraps `Dialog.Viewport` from Shards UI.

## Examples

### Open from a Menu

<ComponentPreview name="p-dialog-2" />

### Dialog with Bare Footer

<ComponentPreview name="p-dialog-6" />

### Dialog with scroll inside

<ComponentPreview name="p-dialog-5" />

### Nested Dialogs

<ComponentPreview name="p-dialog-3" />

### Close Confirmation

<ComponentPreview name="p-dialog-4" />


---

## Document: Drawer

# Drawer

> A panel that slides in from the edge of the screen with swipe gestures, snap points, and nested drawer support.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/drawer)

<ComponentPreview name="p-drawer-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/drawer.json" />

## Usage

```svelte
<script lang="ts">
  import * as Drawer from "$lib/components/ui/drawer/index.js";
</script>

<Drawer.Root>
  <Drawer.Trigger>Open</Drawer.Trigger>
  <Drawer.Popup>
    <Drawer.Header>
      <Drawer.Title>Drawer Title</Drawer.Title>
      <Drawer.Description>Drawer Description</Drawer.Description>
    </Drawer.Header>
    <Drawer.Panel>Content</Drawer.Panel>
    <Drawer.Footer>
      <Drawer.Close>Close</Drawer.Close>
    </Drawer.Footer>
  </Drawer.Popup>
</Drawer.Root>
```

## API Reference

### Drawer.Root

Root component. Wraps `Drawer.Root` from Shards UI with automatic `swipeDirection` mapping based on `position`.

| Prop             | Type                                     | Default    | Description                                                                                                                 |
| ---------------- | ---------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `position`       | `"right" \| "left" \| "top" \| "bottom"` | `"bottom"` | Controls which edge the drawer opens from. Sets the swipe direction automatically and flows to child components via context |
| `swipeDirection` | `"up" \| "down" \| "left" \| "right"`    | derived    | Overrides the swipe direction derived from `position`. Use when you need different swipe behavior                           |

All other props from `Drawer.Root` are supported, including `open`, `onOpenChange`, `modal`, `snapPoints`, `snapPoint`, `onSnapPointChange`, and `snapToSequentialPoints`. Note: Snap points only work for bottom drawers.

### Drawer.createHandle

Creates a handle for detached drawer triggers. Use it when triggers and drawer content need to be coordinated across different parts of the tree.

### Drawer.Trigger

Trigger button that opens the drawer. Wraps `Drawer.Trigger` from Shards UI.

### Drawer.Popup

Popup container that displays the drawer content.

| Prop              | Type                                   | Default     | Description                                                                                                              |
| ----------------- | -------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| `variant`         | `"default" \| "straight" \| "inset"`   | `"default"` | Controls the drawer style. `straight` removes rounded corners, `inset` adds spacing around the drawer on desktop screens |
| `showCloseButton` | `boolean`                              | `false`     | When true, displays a close button in the top-right corner                                                               |
| `showBar`         | `boolean`                              | `false`     | When true, displays a drag bar indicator                                                                                 |
| `portalProps`     | `ComponentProps<typeof Drawer.Portal>` | -           | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see the Shards UI Drawer portal API           |

**Example:**

```svelte
<!-- Bottom drawer (default) -->
<Drawer.Root><Drawer.Popup>...</Drawer.Popup></Drawer.Root>

<!-- Right side drawer -->
<Drawer.Root position="right"><Drawer.Popup>...</Drawer.Popup></Drawer.Root>

<!-- Left side drawer -->
<Drawer.Root position="left"><Drawer.Popup>...</Drawer.Popup></Drawer.Root>

<!-- Drawer with inset variant -->
<Drawer.Root position="right"><Drawer.Popup variant="inset">...</Drawer.Popup></Drawer.Root>
```

### Drawer.Header

Container for the drawer title and description. Supports the `as` prop for polymorphic composition (for example, `as="header"`).

| Prop             | Type      | Default | Description                                                                                              |
| ---------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `allowSelection` | `boolean` | `false` | When true, wraps the header in `Drawer.Content` to reduce swipe interference during mouse text selection |

### Drawer.Footer

Footer section for action buttons. Supports the `as` prop for polymorphic composition.

| Prop             | Type                  | Default     | Description                                                                                              |
| ---------------- | --------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `variant`        | `"default" \| "bare"` | `"default"` | Controls the footer styling. `default` includes border and background, `bare` removes them               |
| `allowSelection` | `boolean`             | `true`      | When true, wraps the footer in `Drawer.Content` to reduce swipe interference during mouse text selection |

### Drawer.Title

Title component. Wraps `Drawer.Title` from Shards UI.

### Drawer.Description

Description component. Wraps `Drawer.Description` from Shards UI.

### Drawer.Panel

Content container. When `scrollable` is true (default), wraps content in a `ScrollArea` component. Supports the `as` prop for polymorphic composition.

| Prop             | Type      | Default | Description                                                                                             |
| ---------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `scrollable`     | `boolean` | `true`  | When true, wraps content in a `ScrollArea`. Set to false for non-scrollable content                     |
| `scrollFade`     | `boolean` | `true`  | When true, shows a fade effect at scroll edges (only applies when `scrollable` is true)                 |
| `allowSelection` | `boolean` | `true`  | When true, wraps the panel in `Drawer.Content` to reduce swipe interference during mouse text selection |

### Drawer.Menu

Container for drawer menu items. Use with `Drawer.MenuItem`, `Drawer.MenuSeparator`, `Drawer.MenuGroup`, `Drawer.MenuGroupLabel`, `Drawer.MenuCheckboxItem`, `Drawer.MenuRadioGroup`, `Drawer.MenuRadioItem`, and `Drawer.MenuTrigger` to build menus that mirror the Menu component API. Supports the `as` prop for polymorphic composition.

### Drawer.MenuItem

Styled menu item that matches `Menu.Item` appearance. Does not close the drawer — wrap with `Drawer.Close` when close-on-click is needed. Supports the `as` prop for polymorphic composition.

| Prop       | Type                         | Default     | Description                                     |
| ---------- | ---------------------------- | ----------- | ----------------------------------------------- |
| `variant`  | `"default" \| "destructive"` | `"default"` | When `destructive`, uses destructive text color |
| `disabled` | `boolean`                    | —           | When true, disables the item                    |

**Example:** Use `Drawer.Close` with `Drawer.drawerMenuItemVariants()` for a close-on-click menu item: `<Drawer.Close class={Drawer.drawerMenuItemVariants()}>Edit</Drawer.Close>`.

### Drawer.MenuSeparator

Horizontal separator between menu items or groups. Supports the `as` prop for polymorphic composition.

### Drawer.MenuGroup

Container for grouping related menu items. Use with `Drawer.MenuGroupLabel` for labeled sections. Supports the `as` prop for polymorphic composition.

### Drawer.MenuGroupLabel

Label for a `Drawer.MenuGroup` section. Renders muted, smaller text above a group of items. In nested drawers, use as a section title at the top of the menu (no back button needed — swipe to go back). Supports the `as` prop for polymorphic composition.

### Drawer.MenuTrigger

Trigger that opens a nested drawer. Styled like a menu item with a trailing chevron. Use for menu items that open nested drawers (for example, “Add to Playlist” → nested drawer with playlist options). Wraps `Drawer.Trigger` internally.

**Example:** `<Drawer.MenuTrigger>Add to Playlist</Drawer.MenuTrigger>` opens a nested drawer when tapped.

### Drawer.MenuCheckboxItem

Checkbox menu item for independent toggles. Supports `variant="switch"` for toggle-style switches. For selection groups, use `Drawer.MenuRadioGroup` with `Drawer.MenuRadioItem`.

### Drawer.MenuRadioGroup

Container for radio menu items. Use with `Drawer.MenuRadioItem` for mutually exclusive options (for example, “Sort by” with Artist, Album, Title).

### Drawer.MenuRadioItem

Radio menu item. Must be used inside `Drawer.MenuRadioGroup` with a `value` prop.

### Drawer.Close

Close button component. Wraps `Drawer.Close` from Shards UI.

### Drawer.Portal

Portal component for rendering outside the DOM hierarchy. Wraps `Drawer.Portal` from Shards UI.

### Drawer.Backdrop

Backdrop/overlay component. Wraps `Drawer.Backdrop` from Shards UI.

### Drawer.Viewport

Viewport component for positioning. Wraps `Drawer.Viewport` from Shards UI. Typically not used directly — `Drawer.Popup` renders it internally.

### Drawer.Bar

Drag handle indicator shown when `showBar` is true on `Drawer.Popup`. Typically not used directly.

### Drawer.Content

Primitive content wrapper used for polymorphic composition with the `as` prop. Wraps `Drawer.Content` from Shards UI.

## Examples

### Inset variant

<ComponentPreview name="p-drawer-4" />

### Straight variant

<ComponentPreview name="p-drawer-5" />

### Scrollable content

<ComponentPreview name="p-drawer-6" />

### Nested drawers

<ComponentPreview name="p-drawer-7" />

### Snap points

<ComponentPreview name="p-drawer-9" />

### Mobile menu

<ComponentPreview name="p-drawer-11" />

### Responsive dialog

Use `Drawer` on small screens and `Dialog` on larger ones to show the same content in a modal on desktop and a bottom sheet on mobile.

<ComponentPreview name="p-drawer-12" />

### Responsive menu

Pair `Drawer` with `Menu` so actions appear in a dropdown on desktop and a swipe-up sheet on mobile. Use `Drawer.MenuTrigger` for items that open nested drawers on mobile. Nested drawers use `Drawer.MenuGroupLabel` as section titles; swipe to go back.

<ComponentPreview name="p-drawer-13" />


---

## Document: Empty

# Empty

> A container for displaying empty state information.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/empty)

<ComponentPreview name="p-empty-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/empty.json" />

## Usage

```svelte
<script lang="ts">
  import Database01Icon from "@hugeicons/core-free-icons/Database01Icon";
  import * as Avatar from "$lib/components/ui/avatar/index.js";
  import { Button } from "$lib/components/ui/button/index.js";
  import * as Empty from "$lib/components/ui/empty/index.js";
  import HugeiconsIcon from "$lib/hugeicons-icon.svelte";
</script>

<Empty.Root>
  <Empty.Header>
    <Empty.Media variant="icon">
      <HugeiconsIcon aria-hidden="true" icon={Database01Icon} strokeWidth={2} />
    </Empty.Media>
    <Empty.Title>No data</Empty.Title>
    <Empty.Description>No data found</Empty.Description>
  </Empty.Header>
  <Empty.Content>
    <Button>Add data</Button>
  </Empty.Content>
</Empty.Root>
```

## API Reference

The API follows [shadcn/ui's empty component](https://ui.shadcn.com/docs/components/empty), adapted
to Svelte namespace composition.

### Empty.Root

The main component of the empty state. Wraps the `Empty.Header` and `Empty.Content` components.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Empty.Root>
  <Empty.Header />
  <Empty.Content />
</Empty.Root>
```

### Empty.Header

The `Empty.Header` component wraps the empty media, title, and description.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Empty.Header>
  <Empty.Media />
  <Empty.Title />
  <Empty.Description />
</Empty.Header>
```

### Empty.Media

Use the `Empty.Media` component to display the media of the empty state such as an icon or an image. You can also use it to display other components such as an avatar.

| Prop      | Type                  | Default   |
| --------- | --------------------- | --------- |
| `variant` | `"default" \| "icon"` | `default` |
| `class`   | `string`              |           |

```svelte
<Empty.Media variant="icon">
  <HugeiconsIcon aria-hidden="true" icon={Database01Icon} strokeWidth={2} />
</Empty.Media>
```

```svelte
<Empty.Media>
  <Avatar.Root>
    <Avatar.Image src="..." />
    <Avatar.Fallback>JD</Avatar.Fallback>
  </Avatar.Root>
</Empty.Media>
```

### Empty.Title

Use the `Empty.Title` component to display the title of the empty state.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Empty.Title>No data</Empty.Title>
```

### Empty.Description

Use the `Empty.Description` component to display the description of the empty state.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Empty.Description>You do not have any notifications.</Empty.Description>
```

### Empty.Content

Use the `Empty.Content` component to display the content of the empty state such as a button, input or a link.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Empty.Content>
  <Button>Add Project</Button>
</Empty.Content>
```


---

## Document: Field

# Field

> A component that provides labelling and validation for form controls.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/field)

<ComponentPreview name="p-field-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/field.json" />

## Usage

```svelte
<script lang="ts">
  import * as Field from "$lib/components/ui/field/index.js";
  import { Input } from "$lib/components/ui/input/index.js";
</script>

<Field.Root>
  <Field.Label>Name</Field.Label>
  <Input type="text" placeholder="Enter your name" />
  <Field.Description>Visible on your profile</Field.Description>
  <Field.Error>Please enter a valid name</Field.Error>
  <Field.Validity>
    {#snippet children(validity)}
      {#if validity.error}<p>{validity.error}</p>{/if}
    {/snippet}
  </Field.Validity>
</Field.Root>
```

## API Reference

### Field.Root

Root component. Styled wrapper for `Field.Root` from Shards UI with flex column layout.

### Field.Label

Label for the field. Styled wrapper for `Field.Label` from Shards UI.

### Field.Item

Container for field items. Styled wrapper for `Field.Item` from Shards UI.

### Field.Description

Description text for the field. Styled wrapper for `Field.Description` from Shards UI with muted foreground color.

### Field.Error

Error message for the field. Styled wrapper for `Field.Error` from Shards UI with destructive foreground color.

### Field.Control

Alias for `Field.Control` from Shards UI. Use it to register a custom or third-party control with the field context so it participates in labelling, validation, and error state.

`Textarea` does not require `Field.Control`. It wraps the control internally and integrates with `Field` in the same way as `Input` and the other built-in controls.

### Field.Validity

Alias for `Field.Validity` from Shards UI.

## Examples

### Required Field

<ComponentPreview name="p-field-2" />

### Disabled Field

<ComponentPreview name="p-field-3" />

### With Error

Enter an invalid email address and press enter to see the error.

<ComponentPreview name="p-field-4" />

### With Validity

<ComponentPreview name="p-field-5" containerClass="[& .preview>*]:w-full [&_.preview>*]:max-w-80" />

### Input Group

<ComponentPreview name="p-field-6" />

### Autocomplete Field

<ComponentPreview name="p-field-7" />

### Combobox Field

<ComponentPreview name="p-field-8" />

### Combobox Multiple Field

<ComponentPreview name="p-field-9" />

### Textarea Field

<ComponentPreview name="p-field-10" />

### Select Field

<ComponentPreview name="p-field-11" />

### Checkbox Field

<ComponentPreview name="p-field-12" />

### Checkbox Group Field

<ComponentPreview name="p-field-13" />

### Radio Group Field

<ComponentPreview name="p-field-14" />

### Switch Field

<ComponentPreview name="p-field-15" />

### Slider Field

<ComponentPreview name="p-field-16" />

### Number Field

<ComponentPreview name="p-field-17" />

### Complete Form Example

<ComponentPreview name="p-field-18" />


---

## Document: Fieldset

# Fieldset

> A native fieldset element with a legend.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/fieldset)

<ComponentPreview name="p-fieldset-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/fieldset.json" />

## Usage

```svelte
<script lang="ts">
  import * as Fieldset from "$lib/components/ui/fieldset/index.js";

  const uid = $props.id();
  const legendId = `${uid}-legend`;
</script>

<Fieldset.Root {legendId}>
  <Fieldset.Legend id={legendId}>Fieldset legend</Fieldset.Legend>
</Fieldset.Root>
```

## API Reference

### Fieldset.Root

Root component. Styled wrapper for `Fieldset.Root` from Shards UI with native fieldset semantics.

### Fieldset.Legend

Legend for the fieldset. Styled wrapper for the Shards UI fieldset legend with semibold font weight.


---

## Document: Form

# Form

> A form wrapper component that simplifies validation and submission.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/form)

<ComponentPreview name="p-form-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/form.json" />

## Usage

```svelte
<script lang="ts">
  import * as Field from "$lib/components/ui/field/index.js";
  import { Form } from "$lib/components/ui/form/index.js";
  import { Input } from "$lib/components/ui/input/index.js";

  function submit(event: SubmitEvent) {
    event.preventDefault();
    /* handle submit */
  }
</script>

<Form class="flex w-full flex-col gap-4" onsubmit={submit}>
  <Field.Root>
    <Field.Label>Email</Field.Label>
    <Input name="email" type="email" required />
    <Field.Error>Please enter a valid email.</Field.Error>
  </Field.Root>
</Form>
```

## API Reference

### Form

Thin wrapper around Shards UI `Form` with no default layout. Pass `class` for spacing and structure, for example `flex w-full flex-col gap-4` for a vertical field stack.

**Dialog, sheet, drawer:** Place the header outside the form. Wrap the panel and footer only in `<Form class="contents">`, or `<form class="contents">`. The `contents` display value keeps the panel and footer participating correctly in the popup flex layout without nesting the header inside the form.

## Examples

### Using with Zod

<ComponentPreview name="p-form-2" />

## Changelog

- [Apr 17, 2026](/docs/changelog#form) - `Form` no longer applies default layout classes. Pass `class` for stacked fields, such as `flex w-full flex-col gap-4`. For overlays, wrap the panel and footer in `<Form class="contents">` with the header outside.


---

## Document: Frame

# Frame

> A framed container for grouping related information.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/frame)

<ComponentPreview name="p-frame-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/frame.json" />

## Usage

```svelte
<script lang="ts">
  import * as Frame from "$lib/components/ui/frame/index.js";
</script>

<Frame.Root>
  <Frame.Header>
    <Frame.Title>Title</Frame.Title>
    <Frame.Description>Description</Frame.Description>
  </Frame.Header>
  <Frame.Panel>Content</Frame.Panel>
  <Frame.Footer>Footer</Frame.Footer>
</Frame.Root>
```

## API Reference

### Frame.Root

The main container component for grouping related information.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

### Frame.Panel

A panel container for frame content.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Frame.Panel>Content</Frame.Panel>
```

### Frame.Header

Header section for the frame.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Frame.Header>
  <Frame.Title>Title</Frame.Title>
  <Frame.Description>Description</Frame.Description>
</Frame.Header>
```

### Frame.Title

Title text for the frame header.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Frame.Title>Title</Frame.Title>
```

### Frame.Description

Description text for the frame header.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Frame.Description>Description</Frame.Description>
```

### Frame.Footer

Footer section for the frame.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Frame.Footer>Footer</Frame.Footer>
```

## Examples

### Separated Panels

By default, multiple panels are separated with spacing between them.

<ComponentPreview name="p-frame-3" />


---

## Document: Group

# Group

> A component for visually grouping a series of controls.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/group)

<ComponentPreview name="p-group-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/group.json" />

## Usage

```svelte
<script lang="ts">
  import { Button } from "$lib/components/ui/button/index.js";
  import * as Group from "$lib/components/ui/group/index.js";
</script>

<Group.Root>
  <Button>Button</Button>
  <Group.Separator />
  <Button>Button</Button>
</Group.Root>
```

## Accessibility

- `Group.Root` has `role="group"`.
- Use Tab to navigate between the controls in the group.
- Use `aria-label` or `aria-labelledby` to label the group.

```svelte
<Group.Root aria-label="Media controls">
  <Button variant="outline">Play</Button>
  <Group.Separator />
  <Button variant="outline">Pause</Button>
</Group.Root>
```

### Group vs ToggleGroup

- Use `Group.Root` when the controls perform actions.
- Use `ToggleGroup.Root` when the controls toggle state.

## API Reference

### Group.Root

The root visually groups related controls with consistent connected styling.

| Prop          | Type                         | Default        |
| ------------- | ---------------------------- | -------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |

```svelte
<Group.Root>
  <Button>Button 1</Button>
  <Group.Separator />
  <Button>Button 2</Button>
</Group.Root>
```

Nest multiple groups to create complex layouts with spacing. See the [nested groups](#nested-groups) example for more details.

```svelte
<Group.Root>
  <Group.Root>
    <Button>1</Button>
    <Group.Separator />
    <Button>2</Button>
  </Group.Root>
  <Group.Root>
    <Button>Previous</Button>
    <Group.Separator />
    <Button>Next</Button>
  </Group.Root>
</Group.Root>
```

### Group.Separator

The separator visually divides controls within a group.

| Prop          | Type                         | Default      |
| ------------- | ---------------------------- | ------------ |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` |

```svelte
<Group.Root>
  <Button>Button 1</Button>
  <Group.Separator />
  <Button>Button 2</Button>
</Group.Root>
```

Unlike shadcn's ButtonGroup, `Group.Separator` is required between all controls, including outline buttons. It preserves the intended hierarchy and focus states.

### Group.Text

Use this component for text such as labels or prefixes.

| Prop | Type                          | Default  |
| ---- | ----------------------------- | -------- |
| `as` | `keyof HTMLElementTagNameMap` | `"span"` |

```svelte
<Group.Root>
  <Group.Text>https://</Group.Text>
  <Group.Separator />
  <Input placeholder="example.com" />
</Group.Root>
```

Render it as a label when the text names a control.

```svelte
<Group.Root>
  <Group.Text as="label" for="domain" aria-label="Domain">https://</Group.Text>
  <Group.Separator />
  <Input id="domain" placeholder="example.com" />
</Group.Root>
```

## Examples

### With Input

<ComponentPreview name="p-group-2" />

### Small Size

<ComponentPreview name="p-group-3" />

### Large Size

<ComponentPreview name="p-group-4" />

### With Disabled Button

<ComponentPreview name="p-group-5" />

### With Default Buttons

<ComponentPreview name="p-group-6" />

### With Start Labeled Text

<ComponentPreview name="p-group-7" />

### With End Text

<ComponentPreview name="p-group-8" />

### Vertical

<ComponentPreview name="p-group-9" />

### Nested Groups

<ComponentPreview name="p-group-10" />

### With Popup

<ComponentPreview name="p-group-11" />

### With Input Group

<ComponentPreview name="p-group-12" />

### With Menu

<ComponentPreview name="p-group-13" />

### With Select

<ComponentPreview name="p-group-14" />


---

## Document: Input

# Input

> A native input element.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/input)

<ComponentPreview name="p-input-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/input.json" />

## Usage

```svelte
<script lang="ts">
  import { Input } from "$lib/components/ui/input/index.js";
</script>

<Input />
```

## API Reference

### Input

Styled wrapper for the Shards UI Input with custom size options.

| Prop       | Type                                  | Default     | Description                                                                  |
| ---------- | ------------------------------------- | ----------- | ---------------------------------------------------------------------------- |
| `size`     | `"sm" \| "default" \| "lg" \| number` | `"default"` | Controls the input height. Number values pass to the native `size` attribute |
| `unstyled` | `boolean`                             | `false`     | Removes the wrapper styling, including the border and shadow                 |

## Examples

For accessible labelling and validation, prefer using the `Field` component to wrap inputs, or the `Field.Control` component. See some [related examples](/docs/components/field).

### Small Size

<ComponentPreview name="p-input-2" />

### Large Size

<ComponentPreview name="p-input-3" />

### Disabled

<ComponentPreview name="p-input-4" />

### File

<ComponentPreview name="p-input-5" />

### With Label

<ComponentPreview name="p-input-6" />

### With Button

<ComponentPreview name="p-input-7" />

### Form Integration

<ComponentPreview name="p-form-1" />


---

## Document: Input Group

# Input Group

> A flexible component for grouping inputs with addons, buttons, and other elements.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/input-group)

<ComponentPreview name="p-input-group-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/input-group.json" />

## Usage

```svelte
<script lang="ts">
  import * as InputGroup from "$lib/components/ui/input-group/index.js";
  import HugeiconsIcon from "$lib/hugeicons-icon.svelte";
  import Mail01Icon from "@hugeicons/core-free-icons/Mail01Icon";
</script>

<InputGroup.Root>
  <InputGroup.Input type="email" placeholder="Email" />
  <InputGroup.Addon>
    <HugeiconsIcon aria-hidden="true" icon={Mail01Icon} strokeWidth={2} />
  </InputGroup.Addon>
</InputGroup.Root>
```

## API Reference

### InputGroup.Root

The main component that wraps inputs and addons.

| Prop       | Type                             | Description            |
| ---------- | -------------------------------- | ---------------------- |
| `class`    | `string`                         | Additional CSS classes |
| `...props` | `HTMLAttributes<HTMLDivElement>` | Native div attributes  |

### InputGroup.Addon

A container for icons, text, buttons, and other elements. It can appear at the inline start, inline end, block start, or block end.

| Prop       | Type                                                             | Default          | Description                    |
| ---------- | ---------------------------------------------------------------- | ---------------- | ------------------------------ |
| `align`    | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` | Position relative to the input |
| `class`    | `string`                                                         |                  | Additional CSS classes         |
| `...props` | `HTMLAttributes<HTMLDivElement>`                                 |                  | Native div attributes          |

<Callout>
  For proper focus navigation, the `InputGroup.Addon` component should be placed after the input in
  the DOM order.
</Callout>

### InputGroup.Text

A text container for content within an addon. It styles muted text and child icons.

| Prop       | Type                              | Description            |
| ---------- | --------------------------------- | ---------------------- |
| `class`    | `string`                          | Additional CSS classes |
| `...props` | `HTMLAttributes<HTMLSpanElement>` | Native span attributes |

### InputGroup.Input

An unstyled `Input` that inherits the parent input-group styling. It accepts the same props as `Input`.

| Prop       | Type         | Description                                          |
| ---------- | ------------ | ---------------------------------------------------- |
| `class`    | `string`     | Additional CSS classes                               |
| `...props` | `InputProps` | All `Input` props, including native input attributes |

### InputGroup.Textarea

An unstyled `Textarea` that inherits the parent input-group styling. It accepts the same props as `Textarea`.

| Prop       | Type            | Description                                                |
| ---------- | --------------- | ---------------------------------------------------------- |
| `class`    | `string`        | Additional CSS classes                                     |
| `...props` | `TextareaProps` | All `Textarea` props, including native textarea attributes |

## Examples

### With End Icon

<ComponentPreview name="p-input-group-2" />

### With Start Text

<ComponentPreview name="p-input-group-3" />

### With End Text

<ComponentPreview name="p-input-group-4" />

### With Start and End Text

<ComponentPreview name="p-input-group-5" />

### With Tooltip

<ComponentPreview name="p-input-group-7" />

### With Icon Button

<ComponentPreview name="p-input-group-8" />

### With Button

<ComponentPreview name="p-input-group-9" />

### With Badge

<ComponentPreview name="p-input-group-10" />

### With Keyboard Shortcut

<ComponentPreview name="p-input-group-11" />

### With Inner Label

<ComponentPreview name="p-input-group-12" />

### Small Size

<ComponentPreview name="p-input-group-13" />

### Large Size

<ComponentPreview name="p-input-group-14" />

### Disabled

<ComponentPreview name="p-input-group-15" />

### Loading

<ComponentPreview name="p-input-group-16" />

### With Number Field

<ComponentPreview name="p-input-group-6" />

### With Textarea

<ComponentPreview name="p-input-group-17" />


---

## Document: Kbd

# Kbd

> A component for displaying keyboard keys and shortcuts.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/kbd)

<ComponentPreview name="p-kbd-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/kbd.json" />

## Usage

```svelte
<script lang="ts">
  import * as Kbd from "$lib/components/ui/kbd/index.js";
</script>
```

Single key:

```svelte
<Kbd.Root>K</Kbd.Root>
```

Multiple keys:

```svelte
<Kbd.Group>
  <Kbd.Root>⌘</Kbd.Root>
  <Kbd.Root>K</Kbd.Root>
</Kbd.Group>
```

## API Reference

### Kbd.Root

Displays a single keyboard key. Native `kbd` attributes pass to the element.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

### Kbd.Group

Groups multiple keyboard keys for key combinations.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

## Examples

### Input Group

<ComponentPreview name="p-input-group-11" class="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />


---

## Document: Label

# Label

> Renders an accessible label associated with controls.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/label)

<ComponentPreview name="p-input-6" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/label.json" />

## Usage

```svelte
<script lang="ts">
  import { Label } from "$lib/components/ui/label/index.js";
</script>

<Label for="email">Email</Label>
```

## API Reference

This is a native Svelte label wrapper rather than a Shards UI part.

### Label

A label component that can render as a different element.

| Prop | Type                          | Default   | Description                 |
| ---- | ----------------------------- | --------- | --------------------------- |
| `as` | `keyof HTMLElementTagNameMap` | `"label"` | Renders a different element |

## Examples

For accessible labelling and validation, prefer using `Field.Label`. See some [related examples](/docs/components/field).

### With Checkbox

<ComponentPreview name="p-checkbox-1" />


---

## Document: Menu

# Menu

> A list of actions in a dropdown, enhanced with keyboard navigation.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/menu)

<ComponentPreview name="p-menu-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/menu.json" />

## Usage

```svelte
<script lang="ts">
  import * as Menu from "$lib/components/ui/menu/index.js";
</script>

<Menu.Root>
  <Menu.Trigger>Open menu</Menu.Trigger>
  <Menu.Popup align="start" sideOffset={4}>
    <Menu.Item>Profile</Menu.Item>
    <Menu.Separator />
    <Menu.Group>
      <Menu.GroupLabel>Playback</Menu.GroupLabel>
      <Menu.Item>Play</Menu.Item>
      <Menu.Item>Pause</Menu.Item>
    </Menu.Group>
    <Menu.Separator />
    <Menu.CheckboxItem>Shuffle</Menu.CheckboxItem>
    <Menu.CheckboxItem>Repeat</Menu.CheckboxItem>
    <Menu.CheckboxItem variant="switch">Auto save</Menu.CheckboxItem>
    <Menu.Separator />
    <Menu.Sub>
      <Menu.SubTrigger>Add to playlist</Menu.SubTrigger>
      <Menu.SubPopup>
        <Menu.Item>Jazz</Menu.Item>
        <Menu.Item>Rock</Menu.Item>
      </Menu.SubPopup>
    </Menu.Sub>
  </Menu.Popup>
</Menu.Root>
```

## API Reference

### Menu.Root

Root component. Alias for `Menu.Root` from Shards UI. Also exported as `DropdownMenu`.

### Menu.Trigger

Trigger button that opens the menu. Alias for `Menu.Trigger` from Shards UI. Also exported as `DropdownMenuTrigger`.

### Menu.Popup

Popup container that displays the menu content. Also exported as `DropdownMenuContent`.

| Prop          | Type                                     | Default    | Description                               |
| ------------- | ---------------------------------------- | ---------- | ----------------------------------------- |
| `side`        | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Side of the trigger to position the popup |
| `align`       | `"start" \| "center" \| "end"`           | `"center"` | Alignment relative to the trigger         |
| `sideOffset`  | `number`                                 | `4`        | Distance from the trigger in pixels       |
| `alignOffset` | `number`                                 | -          | Offset along the alignment axis           |
| `portalProps` | `MenuPopupProps["portalProps"]`          | -          | Props forwarded to the internal portal    |

### Menu.Group

Groups related menu items. Alias for `Menu.Group` from Shards UI. Also exported as `DropdownMenuGroup`.

### Menu.Item

Individual menu item. Also exported as `DropdownMenuItem`.

| Prop      | Type                         | Default     | Description                                           |
| --------- | ---------------------------- | ----------- | ----------------------------------------------------- |
| `inset`   | `boolean`                    | -           | Adds left padding to align with items that have icons |
| `variant` | `"default" \| "destructive"` | `"default"` | Controls the item styling                             |

**Using `inset`:** When mixing items with and without icons, use `inset` on icon-less items to maintain alignment:

```svelte
<Menu.Item><PencilIcon /> Edit</Menu.Item>
<Menu.Item><DeleteIcon /> Delete</Menu.Item>
<Menu.Item inset>Profile</Menu.Item>
```

### Menu.LinkItem

Link menu item for navigation. **`LinkItem`** renders a native **`<a>`** when you pass **`href`**. Styled like **`Menu.Item`**.

| Prop           | Type                         | Default     | Description                                           |
| -------------- | ---------------------------- | ----------- | ----------------------------------------------------- |
| `inset`        | `boolean`                    | -           | Adds left padding to align with items that have icons |
| `variant`      | `"default" \| "destructive"` | `"default"` | Controls the item styling                             |
| `closeOnClick` | `boolean`                    | `true`      | Whether the menu closes when the link is clicked      |

Use **`href`** for plain anchor links:

```svelte
<Menu.LinkItem href="/docs">Docs</Menu.LinkItem>
```

### Menu.CheckboxItem

Checkbox menu item. Also exported as `DropdownMenuCheckboxItem`.

| Prop      | Type                    | Default     | Description                                             |
| --------- | ----------------------- | ----------- | ------------------------------------------------------- |
| `variant` | `"default" \| "switch"` | `"default"` | Display style; `switch` shows a toggle switch indicator |

### Menu.RadioGroup

Groups radio menu items. Alias for `Menu.RadioGroup` from Shards UI. Also exported as `DropdownMenuRadioGroup`.

### Menu.RadioItem

Radio menu item. Styled wrapper for `Menu.RadioItem` from Shards UI. Also exported as `DropdownMenuRadioItem`.

### Menu.GroupLabel

Label for a menu group. Also exported as `DropdownMenuLabel`.

| Prop    | Type      | Default | Description                                           |
| ------- | --------- | ------- | ----------------------------------------------------- |
| `inset` | `boolean` | -       | Adds left padding to align with items that have icons |

### Menu.Separator

Visual separator between menu items. Styled wrapper for `Menu.Separator` from Shards UI. Also exported as `DropdownMenuSeparator`.

### Menu.Shortcut

Displays keyboard shortcut text. Custom component. Also exported as `DropdownMenuShortcut`.

### Menu.Sub

Submenu container. Alias for `Menu.Sub` from Shards UI. Also exported as `DropdownMenuSub`.

### Menu.SubTrigger

Trigger for opening a submenu. Also exported as `DropdownMenuSubTrigger`.

| Prop    | Type      | Default | Description                                           |
| ------- | --------- | ------- | ----------------------------------------------------- |
| `inset` | `boolean` | -       | Adds left padding to align with items that have icons |

### Menu.SubPopup

Popup for submenu content. Also exported as `DropdownMenuSubContent`.

| Prop          | Type                           | Default   | Description                                                               |
| ------------- | ------------------------------ | --------- | ------------------------------------------------------------------------- |
| `align`       | `"start" \| "center" \| "end"` | `"start"` | Alignment relative to the trigger                                         |
| `sideOffset`  | `number`                       | `0`       | Distance from the trigger in pixels                                       |
| `alignOffset` | `number`                       | `-5`      | Offset along the alignment axis; defaults to `-5` unless `align="center"` |

## Examples

### Open on Hover

<ComponentPreview name="p-menu-2" />

### With Checkbox

<ComponentPreview name="p-menu-3" />

### With Switch

`Menu.CheckboxItem` supports a `variant="switch"` prop that displays a decorative switch indicator instead of a checkmark. This is a purely visual variant - the component remains a checkbox item with the same functionality.

<ComponentPreview name="p-menu-9" />

### With Radio Group

<ComponentPreview name="p-menu-4" />

### With Link

<ComponentPreview name="p-menu-5" />

### With Group Label

<ComponentPreview name="p-menu-6" />

### Nested Menu

<ComponentPreview name="p-menu-7" />

### Close on Click

<ComponentPreview name="p-menu-8" />

### Open a Dialog

<ComponentPreview name="p-dialog-2" />


---

## Document: Meter

# Meter

> A graphical display of a numeric value within a range.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/meter)

<ComponentPreview name="p-meter-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/meter.json" />

## Usage

```svelte
<script lang="ts">
  import * as Meter from "$lib/components/ui/meter/index.js";
</script>

<Meter.Root value={40}>
  <Meter.Label>Progress</Meter.Label>
  <Meter.Value />
  <Meter.Track>
    <Meter.Indicator />
  </Meter.Track>
</Meter.Root>
```

## API Reference

### Meter.Root

Root component. Styled wrapper for `Meter.Root` from Shards UI with a flex column layout.

### Meter.Track

Track container for the meter indicator. Styled wrapper for `Meter.Track` from Shards UI.

### Meter.Indicator

Visual indicator showing the current value. Styled wrapper for `Meter.Indicator` from Shards UI.

### Meter.Label

Label text for the meter. Styled wrapper for `Meter.Label` from Shards UI.

### Meter.Value

Displays the current value. Styled wrapper for `Meter.Value` from Shards UI.

See the [Shards Meter API](https://shardsui.com/svelte/meter) for range, formatting, and primitive props.

## Examples

### Without Label and Value

<ComponentPreview name="p-meter-2" />

### With Formatted Value

<ComponentPreview name="p-meter-3" />

### With Range

<ComponentPreview name="p-meter-4" />


---

## Document: Number Field

# Number Field

> A numeric input element with increment and decrement buttons, and a scrub area.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/number-field)

<ComponentPreview name="p-number-field-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/number-field.json" />

## Usage

```svelte
<script lang="ts">
  import * as NumberField from "$lib/components/ui/number-field/index.js";
</script>

<NumberField.Root defaultValue={0}>
  <NumberField.ScrubArea label="Quantity" />
  <NumberField.Group>
    <NumberField.Decrement />
    <NumberField.Input />
    <NumberField.Increment />
  </NumberField.Group>
</NumberField.Root>
```

## API Reference

### NumberField.Root

Root component for the local Svelte number-field behavior.

| Prop   | Type                        | Default     | Description                                               |
| ------ | --------------------------- | ----------- | --------------------------------------------------------- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Controls the size of all child components through context |

### NumberField.Group

Container for the input and buttons.

### NumberField.Input

Input element for the numeric value.

### NumberField.Increment

Button that increments the value and displays the Hugeicons add glyph.

### NumberField.Decrement

Button that decrements the value and displays the Hugeicons minus glyph.

### NumberField.ScrubArea

Draggable area for scrubbing the value.

| Prop    | Type     | Default | Description                            |
| ------- | -------- | ------- | -------------------------------------- |
| `label` | `string` | -       | Label text displayed in the scrub area |

## Examples

For accessible labelling and validation, prefer using `Field` to wrap number fields. See [Number field](/docs/components/field#number-field).

### Small Size

<ComponentPreview name="p-number-field-2" />

### Large Size

<ComponentPreview name="p-number-field-3" />

### Disabled

<ComponentPreview name="p-number-field-4" />

### With External Label

<ComponentPreview name="p-number-field-5" />

### With Scrub

<ComponentPreview name="p-number-field-6" />

### With Range

<ComponentPreview name="p-number-field-7" />

### With Formatted Value

<ComponentPreview name="p-number-field-8" />

### With Step

<ComponentPreview name="p-number-field-9" />

### Form Integration

<ComponentPreview name="p-number-field-10" />


---

## Document: OTP Field

# OTP Field

> A segmented input for one-time passwords and verification codes.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/otp-field)

<ComponentPreview name="p-otp-field-1" />

This component provides a Svelte implementation of the COSS OTP Field behavior. Each slot is a real native input.

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/otp-field.json" />

## Usage

```svelte
<script lang="ts">
  import * as OTPField from "$lib/components/ui/otp-field/index.js";
</script>

<OTPField.Root aria-label="Verification code" length={6}>
  <OTPField.Input />
  <OTPField.Input aria-label="Character 2 of 6" />
  <OTPField.Input aria-label="Character 3 of 6" />
  <OTPField.Separator />
  <OTPField.Input aria-label="Character 4 of 6" />
  <OTPField.Input aria-label="Character 5 of 6" />
  <OTPField.Input aria-label="Character 6 of 6" />
</OTPField.Root>
```

## API Reference

Each slot is a real `<input>`. Its order in the tree must match `length` on the root.

### OTPField.Root

Root component. `class` merges with the default layout styles.

Use required `length` for the number of characters. The previous `maxLength` prop from the legacy `input-otp` package is not used.

| Prop             | Type                                               | Default     | Description                           |
| ---------------- | -------------------------------------------------- | ----------- | ------------------------------------- |
| `size`           | `"default" \| "lg"`                                | `"default"` | Size applied to all slots             |
| `validationType` | `"numeric" \| "alpha" \| "alphanumeric" \| "none"` | `"numeric"` | Accepted character set                |
| `mask`           | `boolean`                                          | `false`     | Masks entered characters in each slot |

### OTPField.Input

Renders one OTP character input. Slots use DOM order and do not take an index prop.

| Prop          | Type     | Description                         |
| ------------- | -------- | ----------------------------------- |
| `class`       | `string` | Merges with the default slot styles |
| `placeholder` | `string` | Native placeholder text             |

Label the OTP control on the root with `aria-label` or a visible `Label` or `Field.Label`. The first input inherits the field label. Give later slots an explicit label such as `Character 2 of 6`.

### OTPField.Separator

Visual separator between slot groups. It uses the design-system Separator for layout and semantics.

## Examples

### Large

<ComponentPreview name="p-otp-field-2" />

### With Separator

<ComponentPreview name="p-otp-field-3" />

### With Label

<ComponentPreview name="p-otp-field-4" />

### Custom normalization

Set `validationType="none"` with `normalizeValue` to normalize pasted input before it reaches state, or to enforce custom character rules. Use `inputMode` for the virtual keyboard hint and `onValueInvalid` for characters rejected after normalization.

<ComponentPreview name="p-otp-field-6" />

### Auto Validation

<ComponentPreview name="p-otp-field-7" />

### Alphanumeric

Use `validationType="alphanumeric"` for recovery, backup, or invite codes that mix letters and numbers.

<ComponentPreview name="p-otp-field-8" />

### Placeholder hints

Each slot is a real input, so `placeholder` and CSS work as usual. Hide the placeholder on focus when the active slot should not show a hint.

<ComponentPreview name="p-otp-field-9" />

### Masked entry

Pass `mask` on the root when the code should be obscured while it is typed, for example on shared screens.

<ComponentPreview name="p-otp-field-10" />

## Changelog

- [Apr 14, 2026](/docs/changelog#otp-field) - `input-otp.tsx` was replaced by `otp-field.tsx` and `@coss/otp-field` upstream.


---

## Document: Pagination

# Pagination

> A pagination with page navigation, next and previous links.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/pagination)

<ComponentPreview name="p-pagination-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/pagination.json" />

## Usage

```svelte
<script lang="ts">
  import * as Pagination from "$lib/components/ui/pagination/index.js";
</script>

<Pagination.Root>
  <Pagination.Content>
    <Pagination.Item><Pagination.Previous href="#previous" /></Pagination.Item>
    <Pagination.Item><Pagination.Link href="#page-1">1</Pagination.Link></Pagination.Item>
    <Pagination.Item><Pagination.Ellipsis /></Pagination.Item>
    <Pagination.Item><Pagination.Next href="#next" /></Pagination.Item>
  </Pagination.Content>
</Pagination.Root>
```

## API Reference

This is a custom Svelte component, not a Shards wrapper.

### Pagination.Root

Root navigation container with `aria-label="pagination"`.

### Pagination.Content

Unordered list container for pagination items.

### Pagination.Item

Individual list item container.

### Pagination.Link

Link for page numbers. `isActive` adds `aria-current="page"` and the active visual treatment. Use
`as` to render another native element.

| Prop       | Type                          | Default  | Description                             |
| ---------- | ----------------------------- | -------- | --------------------------------------- |
| `isActive` | `boolean`                     |          | Highlights the link as the current page |
| `size`     | `ButtonSize`                  | `"icon"` | Controls the link size                  |
| `as`       | `keyof HTMLElementTagNameMap` | `"a"`    | Native element to render                |

### Pagination.Previous

Link to the previous page. Includes a Hugeicons left chevron and “Previous” text.

### Pagination.Next

Link to the next page. Includes “Next” text and a Hugeicons right chevron.

### Pagination.Ellipsis

Ellipsis indicator for skipped pages with screen reader text “More pages”.


---

## Document: Popover

# Popover

> An accessible popup anchored to a button.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/popover)

<ComponentPreview name="p-popover-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/popover.json" />

## Usage

```svelte
<script lang="ts">
  import * as Popover from "$lib/components/ui/popover/index.js";
</script>

<Popover.Root>
  <Popover.Trigger>Open Popover</Popover.Trigger>
  <Popover.Popup>
    <Popover.Title>Popover Title</Popover.Title>
    <Popover.Description>Popover Description</Popover.Description>
    <Popover.Close>Close</Popover.Close>
  </Popover.Popup>
</Popover.Root>
```

## API Reference

### Popover.Root

Root component. Wraps `Popover.Root` from Shards UI.

### Popover.Trigger

Trigger button that opens the popover. Wraps `Popover.Trigger` from Shards UI.

### Popover.Popup

Popup container that displays the popover content. Also exported as `Popover.Content`.

| Prop           | Type                                                     | Default    | Description                                                                                                     |
| -------------- | -------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- |
| `tooltipStyle` | `boolean`                                                | `false`    | When true, applies tooltip-like styling (smaller padding, arrow)                                                |
| `side`         | `"top" \| "bottom" \| "left" \| "right"`                 | `"bottom"` | Side of the trigger to position the popup                                                                       |
| `align`        | `"start" \| "center" \| "end"`                           | `"center"` | Alignment relative to the trigger                                                                               |
| `sideOffset`   | `number`                                                 | `4`        | Distance from the trigger in pixels                                                                             |
| `alignOffset`  | `number`                                                 | `0`        | Offset along the alignment axis                                                                                 |
| `portalProps`  | `ComponentProps<typeof Popover.PopoverPrimitive.Portal>` | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see the Shards UI Popover portal API |

### Popover.Title

Title text for the popover. Styled wrapper for `Popover.Title` from Shards UI.

### Popover.Description

Description text for the popover. Styled wrapper for `Popover.Description` from Shards UI.

### Popover.Close

Close button for the popover. Wraps `Popover.Close` from Shards UI.

### Popover.PopoverCreateHandle

Creates a handle for detached popover triggers. Returns a handle object to attach to multiple triggers.

## Examples

### With Close Button

<ComponentPreview name="p-popover-2" />

### Tooltip Style

Use the `tooltipStyle` prop to make a popover look like a tooltip. This is recommended when you have an info icon button whose only purpose is to show additional information. See the [tooltip accessibility guidelines](https://shardsui.com/svelte/tooltip) for best practices.

<ComponentPreview name="p-input-group-7" />

### Animated Popovers

You can create animated popovers that smoothly transition between different triggers using detached triggers. This pattern allows multiple triggers to share a single popover popup, with automatic animations for position, size, and content changes.

To create detached triggers:

1. Create a handle using `Popover.PopoverCreateHandle`
2. Attach the same handle to multiple `Popover.Trigger` components
3. Each trigger provides a `payload` prop containing a content snippet
4. Use a single `Popover.Root` component with the handle to render the popup

<ComponentPreview name="p-popover-3" />


---

## Document: Preview Card

# Preview Card

> A popup that appears when a link is hovered, showing a preview for sighted users.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/preview-card)

<ComponentPreview name="p-preview-card-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/preview-card.json" />

## Usage

```svelte
<script lang="ts">
  import * as PreviewCard from "$lib/components/ui/preview-card/index.js";
</script>

<PreviewCard.Root>
  <PreviewCard.Trigger href="/">Open Preview Card</PreviewCard.Trigger>
  <PreviewCard.Popup>Preview Card Content</PreviewCard.Popup>
</PreviewCard.Root>
```

## API Reference

### PreviewCard.Root

Root component. Wraps `PreviewCard.Root` from Shards UI.

### PreviewCard.Trigger

Trigger element that shows the preview card on hover. Wraps `PreviewCard.Trigger` from Shards UI.

### PreviewCard.Popup

Popup container that displays the preview content. Also exported as `PreviewCard.HoverCardContent`.

| Prop          | Type                                                             | Default    | Description                                                                                                          |
| ------------- | ---------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------- |
| `align`       | `"start" \| "center" \| "end"`                                   | `"center"` | Alignment relative to the trigger                                                                                    |
| `sideOffset`  | `number`                                                         | `4`        | Distance from the trigger in pixels                                                                                  |
| `portalProps` | `ComponentProps<typeof PreviewCard.PreviewCardPrimitive.Portal>` | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see the Shards UI Preview Card portal API |


---

## Document: Progress

# Progress

> Displays the status of a task that takes a long time.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/progress)

<ComponentPreview name="p-progress-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/progress.json" />

## Usage

```svelte
<script lang="ts">
  import * as Progress from "$lib/components/ui/progress/index.js";
</script>

<Progress.Root value={40} />
```

If you render children inside `Progress.Root`, include `Progress.Track` and `Progress.Indicator`. Without them, the bar will not display. When no children are provided, the root renders a default track and indicator.

## API Reference

### Progress.Root

Root component. Styled wrapper for `Progress.Root` from Shards UI. When no children are provided, it renders a track and indicator.

### Progress.Track

Track container for the progress indicator. Styled wrapper for `Progress.Track` from Shards UI.

### Progress.Indicator

Visual indicator showing the current progress. Styled wrapper for `Progress.Indicator` from Shards UI.

### Progress.Label

Label text for the progress bar. Styled wrapper for `Progress.Label` from Shards UI.

### Progress.Value

Displays the current value. Styled wrapper for `Progress.Value` from Shards UI.

See the [Shards Progress API](https://shardsui.com/svelte/progress) for value formatting, status, and primitive props.

## Examples

### With Label and Value

<ComponentPreview name="p-progress-2" />

### With Formatted Value

<ComponentPreview name="p-progress-3" />


---

## Document: Radio Group

# Radio Group

> A set of checkable buttons where no more than one of the buttons can be checked at a time.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/radio-group)

<ComponentPreview name="p-radio-group-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/radio-group.json" />

## Usage

```svelte
<script lang="ts">
  import * as RadioGroup from "$lib/components/ui/radio-group/index.js";
</script>

<RadioGroup.Root defaultValue="next">
  <label><RadioGroup.Item value="next" /> Next.js</label>
  <label><RadioGroup.Item value="vite" /> Vite</label>
  <label><RadioGroup.Item value="astro" /> Astro</label>
</RadioGroup.Root>
```

## API Reference

### RadioGroup.Root

The root owns one selected value. Use `defaultValue` for the initial selection or `bind:value` for
controlled state. Arrow keys move the selection and skip disabled items.

### RadioGroup.Item

Each item needs a unique `value` and includes the COSS indicator. `RadioGroup.Radio` is an alias.

See the [Shards Radio API](https://shardsui.com/svelte/radio) for form, focus, and validation props.

## Examples

For accessible labelling and validation, prefer using the `Field` component to wrap radio buttons. See the related example: [Radio Group field](/docs/components/field#radio-group-field).

For tabs-style mutually exclusive choices, see the [Segmented Control](/docs/components/segmented-control) pattern.

### Disabled

<ComponentPreview name="p-radio-group-2" />

### With Description

<ComponentPreview name="p-radio-group-3" />

### Card Style

<ComponentPreview name="p-radio-group-4" />

### Form Integration

<ComponentPreview name="p-radio-group-5" />


---

## Document: Scroll Area

# Scroll Area

> A native scroll container with custom scrollbars.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/scroll-area)

<ComponentPreview name="p-scroll-area-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/scroll-area.json" />

## Usage

```svelte
<script lang="ts">
  import { ScrollArea } from "$lib/components/ui/scroll-area/index.js";
</script>

<ScrollArea class="h-64 rounded-md border">
  <div class="p-4">
    Just as suddenly as it had begun, the sensation stopped, leaving Alice feeling slightly
    disoriented. She looked around and realized that the room hadn't changed at all - it was she who
    had grown smaller, shrinking down to a fraction of her previous size. Alice felt herself growing
    larger and larger, filling up the entire room until she feared she might burst. The sensation
    was both thrilling and terrifying, as if she were expanding beyond the confines of her own body.
    She wondered if this was what it felt like to be a balloon, swelling with air until it could
    hold no more.
  </div>
</ScrollArea>
```

## API Reference

### ScrollArea

Root component. Styled composition of the Shards `ScrollArea.Root` primitive with custom scrollbar styling.

| Prop                   | Type      | Default | Description                                                                                                                   |
| ---------------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `scrollFade`           | `boolean` | `false` | Masks viewport edges so content fades in/out as you scroll.                                                                   |
| `scrollbarGutter`      | `boolean` | `false` | Reserves space for the scrollbar to prevent layout shifts.                                                                    |
| `fill`                 | `boolean` | `false` | Applies `size-full` to the scroll area content wrapper so flex layouts (e.g. `mt-auto` footers) can fill the viewport height. |
| `clampContentMinWidth` | `boolean` | `true`  | Sets `minWidth: 0` on the content wrapper to avoid spurious horizontal scrollbars in vertical layouts.                        |
| `overscrollContain`    | `boolean` | `false` | Prevents scroll chaining into parent scrollers when the viewport overflows.                                                   |

### ScrollArea.Viewport

Scrollable viewport container. This is the Shards `ScrollAreaPrimitive.Viewport` part used by the styled composition.

### ScrollArea.Scrollbar

Scrollbar track. The styled `ScrollBar` wrapper composes the Shards `ScrollAreaPrimitive.Scrollbar` part.

### ScrollArea.Thumb

Scrollbar thumb. The styled `ScrollBar` wrapper composes the Shards `ScrollAreaPrimitive.Thumb` part.

### ScrollArea.Corner

Corner element when both scrollbars are visible. This maps to `ScrollAreaPrimitive.Corner`.

## Examples

### Scroll Fade

Use `scrollFade` to mask the viewport edges so content subtly fades in and out as you scroll, hinting that more content is available without adding extra UI chrome.

<ComponentPreview name="p-scroll-area-4" />

### Horizontal Scroll

<ComponentPreview name="p-scroll-area-2" />

### Scrollbar Gutter

Enable `scrollbarGutter` to reserve space for the scrollbar when overflow appears, preventing layout shifts as the bar shows or hides.

<ComponentPreview name="p-scroll-area-5" />

### Both Scrollbars

<ComponentPreview name="p-scroll-area-3" />

### Fill viewport (flex layouts)

Use `fill` when the scroll area wraps a flex column that should stretch to the full viewport height—for example, pinning a footer with `mt-auto` inside a sidebar. The built-in **`SidebarContent`** part already passes `fill`; opt in manually for custom layouts:

```svelte
<ScrollArea class="min-h-0 flex-1" fill>
  <div class="flex h-full flex-col">
    <nav><!-- main items --></nav>
    <footer class="mt-auto"><!-- pinned footer --></footer>
  </div>
</ScrollArea>
```

Leave `fill` at the default (`false`) for content-sized areas such as lists, comboboxes, and dialogs where overflow should track child height.

### Overscroll contain

Use **`overscrollContain`** to stop wheel/touch scrolling from chaining into a parent scroller once the viewport hits its edge. Dialog, sheet, drawer, combobox, autocomplete, and sidebar already opt in; pass it yourself for custom nested scroll surfaces.

```svelte
<ScrollArea class="h-64" overscrollContain>
  <div class="p-4"><!-- Long content --></div>
</ScrollArea>
```

Leave it at the default (`false`) for standalone scroll areas where natural scroll chaining is preferred.

### Content min-width

Shards sets its own content sizing on the content wrapper, which can cause unwanted horizontal scroll in vertical lists and panels (dialogs, comboboxes, sidebars). **`clampContentMinWidth`** defaults to **`true`** and applies `min-width: 0` to prevent that.

Horizontal scroll still works when children define their own width (e.g. `w-max`, table min-width). Set **`clampContentMinWidth={false}`** only if horizontal scroll stops working and the child has no explicit width—rare cases like certain flex chains or long unbreakable inline text without overflow handling.

## Changelog

- [July 31, 2026](/docs/changelog#scroll-area-overscroll-contain) — **`ScrollArea`** no longer applies overscroll contain by default; pass optional **`overscrollContain`** for nested surfaces. Dialog, sheet, drawer, combobox, autocomplete, and sidebar already opt in.
- [May 29, 2026](/docs/changelog#scroll-area) — **`ScrollArea`** adds optional **`fill`** (default **`false`**); pass **`fill`** for flex layouts that need the content wrapper to stretch (e.g. sidebar footers with **`mt-auto`**).


---

## Document: Select

# Select

> A common form component for choosing a predefined value in a dropdown menu.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/select)

<ComponentPreview name="p-select-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/select.json" />

## Usage

```svelte
<script lang="ts">
  import * as Select from "$lib/components/ui/select/index.js";

  const items = [
    { label: "Select framework", value: null },
    { label: "SvelteKit", value: "sveltekit" },
    { label: "Vite", value: "vite" },
    { label: "Astro", value: "astro" },
  ];
</script>

<Select.Root {items}>
  <Select.Trigger><Select.Value placeholder="Select a framework" /></Select.Trigger>
  <Select.Popup>
    <Select.Label>Frameworks</Select.Label>
    {#each items as item (item.value)}
      <Select.Item value={item.value}>{item.label}</Select.Item>
    {/each}
  </Select.Popup>
</Select.Root>
```

## API Reference

### Select.Root

Root component. Alias for `Select.Root` from Shards UI.

### Select.Trigger

Trigger button that opens the select dropdown. Styled wrapper for `Select.Trigger` from Shards UI.

| Prop   | Type                        | Default     | Description                      |
| ------ | --------------------------- | ----------- | -------------------------------- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Controls the size of the trigger |

### Select.Value

Displays the selected value. Styled wrapper for `Select.Value` from Shards UI.

### Select.Popup

Popup container for select options. Also exported as `Select.Content`.

| Prop                   | Type                              | Default | Description                               |
| ---------------------- | --------------------------------- | ------- | ----------------------------------------- |
| `alignItemWithTrigger` | `boolean`                         | `true`  | Aligns the selected item with the trigger |
| `sideOffset`           | `number`                          | `4`     | Distance from the trigger in pixels       |
| `portalProps`          | `SelectPopupProps["portalProps"]` | -       | Props forwarded to the internal portal    |

### Select.Item

Individual select option. Styled wrapper for `Select.Item` from Shards UI with built-in indicator.

### Select.Group

Groups related select items. Alias for `Select.Group` from Shards UI.

### Select.Label

Label for all options in the popup. Styled wrapper for `Select.Label` from Shards UI. Clicking it focuses the select trigger without opening the popup.

### Select.GroupLabel

Label for a select group. Styled wrapper for `Select.GroupLabel` from Shards UI.

### Select.Separator

Visual separator between items. Styled wrapper for `Select.Separator` from Shards UI.

### Select.Button

A standalone button styled like a `Select.Trigger`. Use `selectTriggerClass` on other trigger components, such as `Combobox.Trigger` or `Menu.Trigger`, to give them a select-like appearance.

| Prop   | Type                        | Default     | Description                     |
| ------ | --------------------------- | ----------- | ------------------------------- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Controls the size of the button |

```svelte
<script lang="ts">
  import { selectTriggerClass } from "$lib/components/ui/select/index.js";
</script>

<Combobox.Trigger class={selectTriggerClass}>
  <Combobox.Value placeholder="Select a fruit" />
</Combobox.Trigger>
```

## Examples

For accessible labelling and validation, prefer using the `Field` component to wrap selects. See the related example: [Select field](/docs/components/field#select-field).

### Small Size

<ComponentPreview name="p-select-2" />

### Large Size

<ComponentPreview name="p-select-3" />

### Disabled

<ComponentPreview name="p-select-4" />

### Without Item Alignment

<ComponentPreview name="p-select-5" />

### With Groups

<ComponentPreview name="p-select-6" />

### With Label

<ComponentPreview name="p-select-23" />

### Multiple Selection

<ComponentPreview name="p-select-7" />

### With Icon

<ComponentPreview name="p-select-8" />

### Options with Icon

<ComponentPreview name="p-select-9" />

### With Object Values

<ComponentPreview name="p-select-10" />

### SelectButton with Combobox

Use `selectTriggerClass` on `Combobox.Trigger` to create a combobox that looks like a select.

<ComponentPreview name="p-combobox-18" />

### Form Integration

<ComponentPreview name="p-select-11" />


---

## Document: Segmented Control

# Segmented Control

> A visual pattern for presenting related choices, navigation destinations, filters, or content views.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/segmented-control)

<ComponentPreview name="p-radio-group-8" />

## About

A segmented control is a visual pattern, not a standalone behavior. COSS uses the same presentation across several components while preserving the semantics, keyboard interactions, and state model of each underlying primitive.

## Choose the right primitive

| Intent                            | Use                                           | Why                                                                   |
| --------------------------------- | --------------------------------------------- | --------------------------------------------------------------------- |
| Choose one value in a form        | [Radio Group](/docs/components/radio-group)   | Represents a mutually exclusive value and participates in form state. |
| Navigate to another URL or route  | Navigation links                              | Preserves link behavior, browser history, and `aria-current`.         |
| Apply an exclusive filter or mode | [Toggle Group](/docs/components/toggle-group) | Represents the pressed state of an action that may be cleared.        |
| Switch between related panels     | [Tabs](/docs/components/tabs)                 | Connects each tab to an associated content panel.                     |

Choose the primitive from the interaction first, then apply the segmented-control styling. Visual similarity alone is not a reason to use Tabs or Toggle Group.

## Installation

Segmented controls are provided as particles. Install the implementation and size that match your interaction:

| Implementation | Small             | Default           | Large             |
| -------------- | ----------------- | ----------------- | ----------------- |
| Radio Group    | `p-radio-group-7` | `p-radio-group-8` | `p-radio-group-9` |
| Navigation     | `p-navigation-2`  | `p-navigation-1`  | `p-navigation-3`  |

For example, install the default Radio Group version with:

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/p-radio-group-8.json" />

The CLI installs the shared `segmented-control` styling library and the required primitive automatically.

## Shared styling

For a custom composition, install the styling library directly:

```bash
pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/segmented-control.json
```

The library exports a root class, an item recipe, and a shared item layout class for icons:

```svelte
<script lang="ts">
  import {
    segmentedControlItemLayoutClassName,
    segmentedControlItemVariants,
    segmentedControlRootClassName,
  } from "$lib/segmented-control.js";
</script>
```

```svelte
<script lang="ts">
  const itemClassName = segmentedControlItemVariants({
    size: "default",
    state: "checked",
  });
</script>
```

| Option  | Values                                | Description                                                 |
| ------- | ------------------------------------- | ----------------------------------------------------------- |
| `size`  | `"sm" \| "default" \| "lg"`           | Controls item height and horizontal padding.                |
| `state` | `"checked" \| "current" \| "pressed"` | Selects the state attribute used by the underlying element. |

Use `checked` with Radio Group, `current` with navigation links, and `pressed` with Toggle Group. Tabs retain their own animated indicator and do not use the shared state recipe. They reuse `segmentedControlItemLayoutClassName` so icons match the other segmented implementations.

At the outside edges, the item padding and the surface's `p-0.5` inset combine to match the horizontal padding of the corresponding Button size. The outer segmented surface is slightly taller than that Button to optically balance its inset selected item when the controls appear next to each other.

<ComponentSource name="segmented-control" title="lib/segmented-control.ts" />

## Radio options

Use Radio Group when the selected segment represents a mutually exclusive value, especially in forms.

### Small Radio Group

<ComponentPreview name="p-radio-group-7" />

### Default Radio Group

<ComponentPreview name="p-radio-group-8" />

### Large Radio Group

<ComponentPreview name="p-radio-group-9" />

## Navigation

Use links when each segment points to a different destination. Apply `aria-current="page"` to the active link.

### Small Navigation

<ComponentPreview name="p-navigation-2" />

### Default Navigation

<ComponentPreview name="p-navigation-1" />

### Large Navigation

<ComponentPreview name="p-navigation-3" />

## Related content

Use Tabs when each segment controls an associated content panel. Tabs share the visual language of segmented controls but keep their animated indicator, orientation support, and panel semantics.

<ComponentPreview name="p-tabs-1" />


---

## Document: Separator

# Separator

> A separator element accessible to screen readers.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/separator)

<ComponentPreview name="p-separator-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/separator.json" />

## Usage

```svelte
<script lang="ts">
  import { Separator } from "$lib/components/ui/separator/index.js";
</script>

<Separator />
```

## API Reference

### Separator

An accessible dividing line. It renders horizontally by default, exposes its orientation to
assistive technology, forwards native attributes, and keeps the COSS muted border color.

See the [Shards Separator API](https://shardsui.com/svelte/separator) for element and orientation
props.


---

## Document: Sheet

# Sheet

> A flyout that opens from the side of the screen, based on the dialog component.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/sheet)

<ComponentPreview name="p-sheet-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/sheet.json" />

## Usage

```svelte
<script lang="ts">
  import * as Sheet from "$lib/components/ui/sheet/index.js";
</script>

<Sheet.Root>
  <Sheet.Trigger>Open</Sheet.Trigger>
  <Sheet.Popup>
    <Sheet.Header>
      <Sheet.Title>Are you absolutely sure?</Sheet.Title>
      <Sheet.Description>
        This action cannot be undone. This will permanently delete your account and remove your data
        from our servers.
      </Sheet.Description>
    </Sheet.Header>
    <Sheet.Panel>Content</Sheet.Panel>
    <Sheet.Footer>
      <Sheet.Close>Close</Sheet.Close>
    </Sheet.Footer>
  </Sheet.Popup>
</Sheet.Root>
```

## API Reference

### Sheet.Root

Root component. Wraps `Dialog.Root` from Shards UI.

### Sheet.Trigger

Trigger button that opens the sheet. Wraps `Dialog.Trigger` from Shards UI.

### Sheet.Popup

Popup container that displays the sheet content. Also exported as `Sheet.Content`.

| Prop              | Type                                     | Default     | Description                                                                                                    |
| ----------------- | ---------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
| `side`            | `"right" \| "left" \| "top" \| "bottom"` | `"right"`   | Controls which side of the screen the sheet opens from                                                         |
| `variant`         | `"default" \| "inset"`                   | `"default"` | Controls the sheet style. `inset` adds spacing around the sheet on desktop screens                             |
| `showCloseButton` | `boolean`                                | `true`      | When true, displays a close button in the top-right corner                                                     |
| `closeProps`      | `ComponentProps<typeof Dialog.Close>`    | -           | Props forwarded to the internal close button, useful for overriding `aria-label`                               |
| `portalProps`     | `ComponentProps<typeof Dialog.Portal>`   | -           | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see the Shards UI Dialog portal API |

**Example:**

```svelte
<!-- Right side sheet (default) -->
<Sheet.Popup side="right">...</Sheet.Popup>

<!-- Left side sheet -->
<Sheet.Popup side="left">...</Sheet.Popup>

<!-- Top sheet -->
<Sheet.Popup side="top">...</Sheet.Popup>

<!-- Bottom sheet -->
<Sheet.Popup side="bottom">...</Sheet.Popup>

<!-- Sheet with inset variant -->
<Sheet.Popup side="right" variant="inset">...</Sheet.Popup>
```

### Sheet.Header

Container for the sheet title and description. Supports the `as` prop for polymorphic composition (for example, `as="header"`).

### Sheet.Footer

Footer section for action buttons. Supports the `as` prop for polymorphic composition.

| Prop      | Type                  | Default     | Description                                                                                |
| --------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `variant` | `"default" \| "bare"` | `"default"` | Controls the footer styling. `default` includes border and background, `bare` removes them |

### Sheet.Title

Title component. Wraps `Dialog.Title` from Shards UI.

### Sheet.Description

Description component. Wraps `Dialog.Description` from Shards UI.

### Sheet.Panel

Scrollable content container. Automatically wraps content in a `ScrollArea` component. Supports the `as` prop for polymorphic composition.

| Prop         | Type      | Default | Description                                    |
| ------------ | --------- | ------- | ---------------------------------------------- |
| `scrollFade` | `boolean` | `true`  | When true, shows a fade effect at scroll edges |

**Example:**

```svelte
<Sheet.Panel>
  <!-- Long content that will scroll if it exceeds the sheet height -->
  <div>...</div>
</Sheet.Panel>
```

### Sheet.Close

Close button component. Wraps `Dialog.Close` from Shards UI.

### Sheet.Portal

Portal component for rendering outside the DOM hierarchy. Wraps `Dialog.Portal` from Shards UI.

### Sheet.Backdrop

Backdrop/overlay component. Also exported as `Sheet.Overlay`. Wraps `Dialog.Backdrop` from Shards UI.

## Examples

### Sheet with Inset

<ComponentPreview name="p-sheet-2" />

### Side sheets

<ComponentPreview name="p-sheet-3" />


---

## Document: Skeleton

# Skeleton

> A loading state skeleton for your components.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/skeleton)

<ComponentPreview name="p-skeleton-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/skeleton.json" />

## Usage

```svelte
<script lang="ts">
  import { Skeleton } from "$lib/components/ui/skeleton/index.js";
</script>

<Skeleton class="size-10 rounded-full" />
```

## API Reference

### Skeleton

A native `div` with the COSS animated loading gradient. Apply size and shape through `class`; native
attributes, snippets, callbacks, and a bindable `ref` are forwarded.

## Examples

### Skeleton Only

<ComponentPreview name="p-skeleton-2" />


---

## Document: Slider

# Slider

> An input where the user selects a value from within a given range.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/slider)

<ComponentPreview name="p-slider-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/slider.json" />

## Usage

```svelte
<script lang="ts">
  import * as Slider from "$lib/components/ui/slider/index.js";
</script>

<Slider.Root aria-label="Volume" defaultValue={50} />
```

## API Reference

### Slider.Root

The root accepts a number or an array for range sliders. Use `defaultValue` for the initial value or
`bind:value` for controlled state.

| Prop                     | Type                                           | Default        | Description                                                             |
| ------------------------ | ---------------------------------------------- | -------------- | ----------------------------------------------------------------------- |
| `value`                  | `number \| readonly number[]`                  | `min`          | Current value; an array creates a range slider                          |
| `defaultValue`           | `number \| readonly number[]`                  | `min`          | Initial value for uncontrolled use                                      |
| `min`                    | `number`                                       | `0`            | Minimum allowed value                                                   |
| `max`                    | `number`                                       | `100`          | Maximum allowed value                                                   |
| `step`                   | `number`                                       | `1`            | Granularity the value changes by                                        |
| `largeStep`              | `number`                                       | `10`           | Granularity for Page Up, Page Down, and Shift + Arrow                   |
| `orientation`            | `"horizontal" \| "vertical"`                   | `"horizontal"` | Axis the slider runs along                                              |
| `disabled`               | `boolean`                                      | `false`        | Disables the thumb inputs and pointer interaction                       |
| `minStepsBetweenValues`  | `number`                                       | `0`            | Minimum steps between neighboring thumbs                                |
| `thumbCollisionBehavior` | `"push" \| "swap" \| "none"`                   | `"push"`       | Controls what happens when one thumb reaches another                    |
| `thumbAlignment`         | `"center" \| "edge"`                           | `"edge"`       | Aligns thumbs to the track; the COSS wrapper defaults to edge alignment |
| `name`                   | `string`                                       | —              | Name submitted with the form                                            |
| `form`                   | `string`                                       | —              | ID of the owning form when the slider is outside it                     |
| `onValueChange`          | `(value: number \| readonly number[]) => void` | —              | Runs whenever the value changes                                         |
| `onValueCommitted`       | `(value: number \| number[]) => void`          | —              | Runs after pointer or keyboard input settles                            |

### Slider.Value

The value part displays the current formatted value and points to the thumb inputs.

The package also exports `Slider.Control`, `Slider.Track`, `Slider.Indicator`, `Slider.Thumb`, and
`Slider.Label` for custom compositions. See the [Shards Slider API](https://shardsui.com/svelte/slider)
for drag, keyboard, formatting, and form props.

## Examples

For accessible labelling and validation, prefer using the `Field` component to wrap checkboxes. See the related example: [Slider field](/docs/components/field#slider-field).

### With Label and Value

<ComponentPreview name="p-slider-2" />

### Range Slider

<ComponentPreview name="p-slider-3" />

### Vertical

<ComponentPreview name="p-slider-4" />

### Form Integration

<ComponentPreview name="p-slider-5" />


---

## Document: Spinner

# Spinner

> An indicator that can be used to show a loading state.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/spinner)

<ComponentPreview name="p-spinner-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/spinner.json" />

## Usage

```svelte
<script lang="ts">
  import { Spinner } from "$lib/components/ui/spinner/index.js";
</script>

<Spinner />
```

## API Reference

### Spinner

Use the `Spinner` component to display a loading indicator. Native SVG attributes pass to the element.

| Prop                  | Type               | Default |
| --------------------- | ------------------ | ------- |
| `class`               | `string`           |         |
| `size`                | `number \| string` | `24`    |
| `strokeWidth`         | `number \| string` | `2`     |
| `absoluteStrokeWidth` | `boolean`          | `false` |

## Examples

### Input Group

<ComponentPreview name="p-input-12" />

### Button

<ComponentPreview name="p-button-18" />


---

## Document: Switch

# Switch

> A control that indicates whether a setting is on or off.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/switch)

<ComponentPreview name="p-switch-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/switch.json" />

## Usage

```svelte
<script lang="ts">
  import { Switch } from "$lib/components/ui/switch/index.js";
</script>

<Switch aria-label="Marketing emails" />
```

## API Reference

### Switch

`Switch` includes the COSS thumb and responsive sizing. Use `checked` for an initial value or
`bind:checked` for controlled state. Native form props and `onCheckedChange` pass to the Shards root.

See the [Shards Switch API](https://shardsui.com/svelte/switch) for form, validation, and state props.

## Examples

For accessible labelling and validation, prefer using the `Field` component to wrap checkboxes. See the related example: [Switch field](/docs/components/field#switch-field).

### Disabled

<ComponentPreview name="p-switch-2" />

### With Description

<ComponentPreview name="p-switch-3" />

### Customizing Size

The switch size is controlled by the `--thumb-size` CSS variable. By default, the switch uses responsive sizing with `[--thumb-size:--spacing(5)] sm:[--thumb-size:--spacing(4)]` classes, making it slightly larger on mobile devices (like other interactive elements).

You can customize the size by overriding these CSS variable classes on the component. The `--thumb-size` value can be expressed using:

- The spacing scale: `--spacing(3)`, `--spacing(4)`, `--spacing(5)`, etc.
- Fixed units: `1rem`, `16px`, etc.

<ComponentPreview name="p-switch-6" />

### Card Style

<ComponentPreview name="p-switch-4" />

### Form Integration

<ComponentPreview name="p-switch-5" />


---

## Document: Table

# Table

> A simple table component for displaying tabular data.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/table)

<ComponentPreview name="p-table-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/table.json" />

## Usage

```svelte
<script lang="ts">
  import * as Table from "$lib/components/ui/table/index.js";
</script>

<Table.Root>
  <Table.Caption>Caption</Table.Caption>
  <Table.Header>
    <Table.Row>
      <Table.Head>Header</Table.Head>
      <Table.Head>Header</Table.Head>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Cell</Table.Cell>
      <Table.Cell>Cell</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table.Root>
```

## API Reference

### Table.Root

The main table container component. Set `variant="card"` for a card-style table: separated borders, rounded corners, and row surfaces that read as cards. That pairs well with a [Frame](/docs/components/frame) (page chrome) or [CardFrame](/docs/components/card) (card shell with optional header actions). The default variant is a simpler row layout with standard borders.

| Prop      | Type                  | Default     |
| --------- | --------------------- | ----------- |
| `class`   | `string`              |             |
| `variant` | `"default" \| "card"` | `"default"` |

```svelte
<Table.Root>
  <Table.Header>...</Table.Header>
  <Table.Body>...</Table.Body>
</Table.Root>
```

```svelte
<Table.Root variant="card">
  <Table.Header>...</Table.Header>
  <Table.Body>...</Table.Body>
</Table.Root>
```

### Table.Header

Header section of the table containing column headers.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Table.Header>
  <Table.Row>
    <Table.Head>Header</Table.Head>
  </Table.Row>
</Table.Header>
```

### Table.Body

Body section of the table containing table rows and data.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Table.Body>
  <Table.Row>
    <Table.Cell>Cell</Table.Cell>
  </Table.Row>
</Table.Body>
```

### Table.Footer

Footer section of the table.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Table.Footer>
  <Table.Row>
    <Table.Cell>Footer</Table.Cell>
  </Table.Row>
</Table.Footer>
```

### Table.Row

A row in the table.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Table.Row>
  <Table.Cell>Cell</Table.Cell>
</Table.Row>
```

### Table.Head

A header cell in the table.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Table.Head>Header</Table.Head>
```

### Table.Cell

A data cell in the table.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Table.Cell>Cell</Table.Cell>
```

### Table.Caption

A caption for the table.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` |         |

```svelte
<Table.Caption>Caption</Table.Caption>
```

## Examples

### Card-style table

Use `variant="card"` when the grid itself should look like a set of cards (for example dashboards or standalone tables without an outer frame).

<ComponentPreview name="p-table-5" />

### Table in CardFrame

Put the table in [CardFrame](/docs/components/card) so the grid sits inside the card shell (border, radius, clipping). Use `variant="card"` on `Table.Root`. The example below is static markup—no row selection or TanStack.

<ComponentPreview name="p-table-7" />

### Table in Frame

Wrap the table in a [Frame](/docs/components/frame) for bordered app-surface framing. Use `variant="card"` on `Table.Root` so rows keep the card-style treatment inside the frame.

<ComponentPreview name="p-table-2" />

### Data table with TanStack

Use [TanStack Table for Svelte](https://tanstack.com/table/latest/docs/framework/svelte/svelte-table) with `variant="card"` when you need column definitions, row selection, and `flexRender` over the same table primitives. Add `@tanstack/svelte-table` to your project for headless state (sorting, pagination, selection) beyond static markup.

<ComponentPreview name="p-table-6" />

## Changelog

- [Apr 12, 2026](/docs/changelog#table) — `Table.Root` adds optional `variant` (`default` or `card`)


---

## Document: Tabs

# Tabs

> A component for toggling between related panels on the same page.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/tabs)

<ComponentPreview name="p-tabs-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/tabs.json" />

The registry installs the shared segmented-control styling automatically.

## Usage

```svelte
<script lang="ts">
  import * as Tabs from "$lib/components/ui/tabs/index.js";
</script>

<Tabs.Root defaultValue="tab-1">
  <Tabs.List>
    <Tabs.Tab value="tab-1">Tab 1</Tabs.Tab>
    <Tabs.Tab value="tab-2">Tab 2</Tabs.Tab>
    <Tabs.Tab value="tab-3">Tab 3</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="tab-1">Tab 1 content</Tabs.Panel>
  <Tabs.Panel value="tab-2">Tab 2 content</Tabs.Panel>
  <Tabs.Panel value="tab-3">Tab 3 content</Tabs.Panel>
</Tabs.Root>
```

## API Reference

### Tabs.Root

The root component owns selection, orientation, activation, roving focus, and keyboard behavior.
Use `value` and `bind:value` for controlled state, or `defaultValue` for the initial value.

### Tabs.List

The container for tab triggers. It inserts the styled active indicator and provides the shared
`size` and `variant` values.

| Prop      | Type                        | Default     | Description                         |
| --------- | --------------------------- | ----------- | ----------------------------------- |
| `size`    | `"sm" \| "default" \| "lg"` | `"default"` | Controls the size of all tab items. |
| `variant` | `"default" \| "underline"`  | `"default"` | Controls the tab styling.           |

### Tabs.Tab

An individual tab trigger. Shards manages its selected, disabled, and focus states.

### Tabs.Panel

The content panel associated with a tab value.

### Tabs.Indicator

The visual indicator for the active tab. `Tabs.List` includes it automatically; the part remains
available for custom compositions.

See the [Shards Tabs API](https://shardsui.com/svelte/tabs) for activation, focus-loop, orientation,
and mounting props.

## Examples

For guidance on choosing between Tabs, Radio Group, Toggle Group, and navigation links, see the
[Segmented Control](/docs/components/segmented-control) pattern.

Tabs use the same optical sizing as segmented controls. The default surface is slightly taller than
a Button of the same size so its inset active indicator remains visually balanced alongside adjacent
controls.

### Small

<ComponentPreview name="p-tabs-14" />

### Large

<ComponentPreview name="p-tabs-15" />

### Underline Variant

<ComponentPreview name="p-tabs-2" />

### Vertical Orientation

<ComponentPreview name="p-tabs-3" />

### Underline with Vertical Orientation

<ComponentPreview name="p-tabs-4" />


---

## Document: Textarea

# Textarea

> A native textarea element.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/textarea)

<ComponentPreview name="p-textarea-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/textarea.json" />

## Usage

```svelte
<script lang="ts">
  import { Textarea } from "$lib/components/ui/textarea/index.js";
</script>

<Textarea />
```

## Field Integration

Shards UI does not provide a native Textarea part. This component wraps the native `<textarea>` element in `Field.Control` internally, so it integrates with `Field` without another wrapper.

```svelte
<Field.Root>
  <Field.Label>Bio</Field.Label>
  <Textarea placeholder="Tell us about yourself…" />
  <Field.Description>Write a short bio.</Field.Description>
  <Field.Error>This field is required.</Field.Error>
</Field.Root>
```

## API Reference

### Textarea

Styled native textarea element with custom size options.

| Prop       | Type                                  | Default     | Description                                                                      |
| ---------- | ------------------------------------- | ----------- | -------------------------------------------------------------------------------- |
| `size`     | `"sm" \| "default" \| "lg" \| number` | `"default"` | Controls the textarea padding. Number values pass to the native `rows` attribute |
| `unstyled` | `boolean`                             | `false`     | Removes all default styling                                                      |

## Examples

### Small Size

<ComponentPreview name="p-textarea-2" />

### Large Size

<ComponentPreview name="p-textarea-3" />

### Disabled

<ComponentPreview name="p-textarea-4" />

### With Label

<ComponentPreview name="p-textarea-5" />

### Form Integration

<ComponentPreview name="p-textarea-6" />


---

## Document: Toast

# Toast

> A temporary notification that appears on screen to inform users.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/toast)

<ComponentPreview name="p-toast-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/toast.json" />

Add `Toast.Provider` and `Toast.AnchoredProvider` to your app layout.

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import * as Toast from "$lib/components/ui/toast/index.js";
  import type { Snippet } from "svelte";

  let { children }: { children: Snippet } = $props();
</script>

<Toast.Provider>
  <Toast.AnchoredProvider>
    {@render children()}
  </Toast.AnchoredProvider>
</Toast.Provider>
```

## Usage

### Stacked Toasts

```svelte
<script lang="ts">
  import * as Toast from "$lib/components/ui/toast/index.js";

  function createEvent() {
    Toast.toastManager.add({
      title: "Event has been created",
      description: "Monday, January 3rd at 6:00pm",
    });
  }
</script>
```

By default, toasts appear in the **bottom-right** corner. Change this with the `position` prop on `Toast.Provider`.

Allowed values are `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, and `bottom-right`.

```svelte
<Toast.Provider position="top-center">
  {@render children()}
</Toast.Provider>
```

### Deduplicated toasts (upsert)

Pass a stable `id` when calling `Toast.toastManager.add`. If a toast with that `id` already exists, Shards UI updates it in place, refreshes the auto-dismiss timer, and increments `updateKey`. The styled toast replays a short re-notify animation on each update.

```ts
Toast.toastManager.add({
  id: "save-status",
  title: "Saved",
  description: "Your draft was updated.",
});
```

<ComponentPreview name="p-toast-10" />

### Anchored Toasts

For toasts positioned relative to an element, use `Toast.anchoredToastManager`. Add `Toast.AnchoredProvider` to your app layout so components can use the manager directly.

```ts
Toast.anchoredToastManager.add({
  title: "Copied!",
  positionerProps: {
    anchor: button,
  },
});
```

Style an anchored toast like a tooltip with `data: { tooltipStyle: true }`. Tooltip style displays only the title.

```ts
Toast.anchoredToastManager.add({
  title: "Copied!",
  positionerProps: {
    anchor: button,
  },
  data: {
    tooltipStyle: true,
  },
});
```

<ComponentPreview name="p-toast-12" />

## API Reference

### Toast.Provider

Provider component for stacked toasts. Wraps `Toast.Provider` from Shards UI and renders the COSS toast stack.

| Prop           | Type                                                                                              | Default              | Description                                                             |
| -------------- | ------------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------- |
| `position`     | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"bottom-right"`     | Positions the toast viewport                                            |
| `portalProps`  | `ToastPortalProps`                                                                                | —                    | Passes `container`, native attributes, and `ref` to the internal portal |
| `limit`        | `number`                                                                                          | `3`                  | Sets the maximum number of visible stacked toasts                       |
| `timeout`      | `number`                                                                                          | `5000`               | Sets the default auto-dismiss time in milliseconds                      |
| `toastManager` | `ToastManager`                                                                                    | `Toast.toastManager` | Supplies a custom manager instance                                      |

### Toast.AnchoredProvider

Provider component for toasts anchored to elements. Use it with `Toast.anchoredToastManager`.

| Prop           | Type               | Default                      | Description                                                             |
| -------------- | ------------------ | ---------------------------- | ----------------------------------------------------------------------- |
| `portalProps`  | `ToastPortalProps` | —                            | Passes `container`, native attributes, and `ref` to the internal portal |
| `limit`        | `number`           | `3`                          | Sets the maximum number of visible anchored toasts                      |
| `timeout`      | `number`           | `5000`                       | Sets the default auto-dismiss time in milliseconds                      |
| `toastManager` | `ToastManager`     | `Toast.anchoredToastManager` | Supplies a custom manager instance                                      |

### Toast.toastManager

Manager for stacked toasts. Use `Toast.toastManager.add()` to show a toast. A later `add` with the same `id` updates the existing toast instead of stacking a duplicate. Use `close(id)` to dismiss one toast, `close()` to dismiss all toasts, and `promise()` to update a loading toast from a promise result.

### Toast.anchoredToastManager

Manager for anchored toasts. Pass `positionerProps.anchor` to `add()`. Repeated calls with the same `id` update the existing toast.

### Toast.ToastPrimitive.Viewport

Viewport container for toasts. The COSS-styled providers render Shards UI's `Toast.Viewport`
internally. Use `Toast.ToastPrimitive.Viewport` for a custom lower-level composition.

### Toast.ToastPrimitive.Root

Individual toast container. The COSS-styled providers render Shards UI's `Toast.Root` internally.
Use `Toast.ToastPrimitive.Root` for a custom lower-level composition.

### Toast.ToastPrimitive.Title

Title text for the toast. The providers render `Toast.ToastPrimitive.Title` from each manager
record's `title` value.

### Toast.ToastPrimitive.Description

Description text for the toast. The providers render `Toast.ToastPrimitive.Description` from each
manager record's `description` value.

### Toast.ToastPrimitive.Action

Action button for the toast. Set `actionProps` when adding a toast; the providers render the action
with the COSS small-button style through `Toast.ToastPrimitive.Action`.

### Toast.ToastPrimitive.Close

Close control for a custom toast composition. Use `Toast.ToastPrimitive.Close`, or call
`Toast.toastManager.close(id)` and `Toast.anchoredToastManager.close(id)` from application logic.

See the [Shards Toast API](https://shardsui.com/svelte/toast) for manager options, swipe behavior,
priority, focus management, and primitive props.

## Examples

### With Status

<ComponentPreview name="p-toast-2" />

### Loading

<ComponentPreview name="p-toast-3" />

### With Action

<ComponentPreview name="p-toast-4" />

### Promise

<ComponentPreview name="p-toast-5" />

### With Varying Heights

<ComponentPreview name="p-toast-6" />

### Copy Button with Anchored Toast

<ComponentPreview name="p-toast-7" />

### Submit Button with Error Toast

<ComponentPreview name="p-toast-8" />


---

## Document: Toggle

# Toggle

> A two-state button that can be toggled on or off.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/toggle)

<ComponentPreview name="p-toggle-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/toggle.json" />

## Usage

```svelte
<script lang="ts">
  import { Toggle } from "$lib/components/ui/toggle/index.js";
</script>

<Toggle>Toggle</Toggle>
```

## API Reference

### Toggle

Styled wrapper for the Shards toggle with variant and size options.

| Prop              | Type                          | Default     | Description                                    |
| ----------------- | ----------------------------- | ----------- | ---------------------------------------------- |
| `variant`         | `"default" \| "outline"`      | `"default"` | Controls the toggle styling                    |
| `size`            | `"default" \| "sm" \| "lg"`   | `"default"` | Controls the toggle size                       |
| `pressed`         | `boolean`                     | `false`     | Current pressed state; supports `bind:pressed` |
| `onPressedChange` | `(pressed: boolean) => void`  | —           | Runs when the pressed state changes            |
| `disabled`        | `boolean`                     | `false`     | Prevents focus and activation                  |
| `value`           | `string`                      | auto        | Identifies the toggle inside a Toggle Group    |
| `as`              | `keyof HTMLElementTagNameMap` | `"button"`  | HTML element to render                         |

See the [Shards Toggle API](https://shardsui.com/svelte/toggle) for state and keyboard props.

## Examples

### Outline

<ComponentPreview name="p-toggle-2" />

### With Icon

<ComponentPreview name="p-toggle-3" />

### Small Size

<ComponentPreview name="p-toggle-4" />

### Large Size

<ComponentPreview name="p-toggle-5" />

### Disabled

<ComponentPreview name="p-toggle-6" />

### Icon Group

<ComponentPreview name="p-toggle-7" />


---

## Document: Toggle Group

# Toggle Group

> Provides a shared state to a series of toggle buttons.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/toggle-group)

<ComponentPreview name="p-toggle-group-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/toggle-group.json" />

## Usage

```svelte
<script lang="ts">
  import * as ToggleGroup from "$lib/components/ui/toggle-group/index.js";
</script>

<ToggleGroup.Root>
  <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
  <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item>
  <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item>
</ToggleGroup.Root>
```

## API Reference

### ToggleGroup.Root

The root owns the selection and shares its styling and interaction state with the child toggles.

| Prop            | Type                          | Default        | Description                                    |
| --------------- | ----------------------------- | -------------- | ---------------------------------------------- |
| `value`         | `readonly string[]`           | `[]`           | Current selection; supports `bind:value`       |
| `defaultValue`  | `readonly string[]`           | `[]`           | Initial selection for uncontrolled use         |
| `multiple`      | `boolean`                     | `false`        | Allows more than one pressed item              |
| `orientation`   | `"horizontal" \| "vertical"`  | `"horizontal"` | Sets the group axis and arrow-key direction    |
| `disabled`      | `boolean`                     | `false`        | Disables every item in the group               |
| `loopFocus`     | `boolean`                     | `true`         | Wraps arrow-key focus at the ends of the group |
| `onValueChange` | `(value: string[]) => void`   | —              | Runs when the selection changes                |
| `variant`       | `"default" \| "outline"`      | `"default"`    | Controls the styling of all child toggles      |
| `size`          | `"default" \| "sm" \| "lg"`   | `"default"`    | Controls the size of all child toggles         |
| `as`            | `keyof HTMLElementTagNameMap` | `"div"`        | HTML element to render                         |

### ToggleGroup.Item

Each item needs a unique `value`. It accepts the Toggle props and inherits `variant` and `size` from
the root. Arrow keys, Home, and End move focus within the group.

### ToggleGroup.Separator

The separator follows the group's orientation and preserves the connected outline treatment.

See the [Shards Toggle Group API](https://shardsui.com/svelte/toggle-group) for focus and selection
behavior.

## Examples

### Small Toggles

<ComponentPreview name="p-toggle-group-2" />

### Large Toggles

<ComponentPreview name="p-toggle-group-3" />

### With Outline Toggles

<ComponentPreview name="p-toggle-group-4" />

### Vertical

<ComponentPreview name="p-toggle-group-5" />

### Disabled

<ComponentPreview name="p-toggle-group-6" />

### With Disabled Toggle

<ComponentPreview name="p-toggle-group-7" />

### Multiple selection

<ComponentPreview name="p-toggle-group-8" />

### With Tooltips

<ComponentPreview name="p-toggle-group-9" />

## Changelog

- [Mar 20, 2026](/docs/changelog#toggle-group) — `Toggle` renamed to `ToggleGroupItem`


---

## Document: Toolbar

# Toolbar

> A container for grouping a set of buttons and controls.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/toolbar)

<ComponentPreview name="p-toolbar-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/toolbar.json" />

## Usage

```svelte
<script lang="ts">
  import * as ToggleGroup from "$lib/components/ui/toggle-group/index.js";
  import * as Toolbar from "$lib/components/ui/toolbar/index.js";
</script>

<Toolbar.Root aria-label="Formatting">
  <Toolbar.Group aria-label="Text style">
    <ToggleGroup.Root multiple>
      <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
      <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item>
    </ToggleGroup.Root>
  </Toolbar.Group>
  <Toolbar.Separator />
  <Toolbar.Button>Save</Toolbar.Button>
</Toolbar.Root>
```

## API Reference

### Toolbar.Root

Groups controls into one roving-focus toolbar.

### Toolbar.Group

Groups related toolbar items.

### Toolbar.Button

A button in the toolbar focus sequence.

### Toolbar.Separator

A separator perpendicular to the toolbar orientation.

### Toolbar.Link

A link in the toolbar focus sequence.


---

## Document: Tooltip

# Tooltip

> A popup that appears when an element is hovered or focused, showing a hint for sighted users.

[Canonical documentation](https://coss-sv.vercel.app/docs/components/tooltip)

<ComponentPreview name="p-tooltip-1" />

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/tooltip.json" />

## Usage

```svelte
<script lang="ts">
  import * as Tooltip from "$lib/components/ui/tooltip/index.js";
</script>

<Tooltip.Root>
  <Tooltip.Trigger>Hover me</Tooltip.Trigger>
  <Tooltip.Popup>Helpful hint</Tooltip.Popup>
</Tooltip.Root>
```

## API Reference

### Tooltip.Root

Root component. Wraps `Tooltip.Root` from Shards UI.

### Tooltip.Trigger

Trigger element that shows the tooltip on hover/focus. Wraps `Tooltip.Trigger` from Shards UI.

### Tooltip.Popup

Popup container that displays the tooltip content. Also exported as `Tooltip.Content`.

| Prop          | Type                                                     | Default    | Description                                                                                                     |
| ------------- | -------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- |
| `side`        | `"top" \| "bottom" \| "left" \| "right"`                 | `"top"`    | Side of the trigger to position the tooltip                                                                     |
| `align`       | `"start" \| "center" \| "end"`                           | `"center"` | Alignment relative to the trigger                                                                               |
| `sideOffset`  | `number`                                                 | `4`        | Distance from the trigger in pixels                                                                             |
| `portalProps` | `ComponentProps<typeof Tooltip.TooltipPrimitive.Portal>` | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see the Shards UI Tooltip portal API |

### Tooltip.Provider

Provider for grouping tooltips. Wraps `Tooltip.Provider` from Shards UI.

### Tooltip.Handle

Creates a handle for detached tooltip triggers. Use `new Tooltip.Handle<Payload>()` to attach multiple triggers to one animated popup.

## Examples

### Grouped Tooltips

To group multiple tooltips so they appear instantly after the first one is opened, wrap them in `Tooltip.Provider`. The grouping logic ensures that once a tooltip becomes visible, the adjacent tooltips will be shown instantly.

<ComponentPreview name="p-tooltip-2" />

### Animated Tooltips

You can create animated tooltips that smoothly transition between different triggers using detached triggers. This pattern allows multiple triggers to share a single tooltip popup, with automatic animations for position, size, and content changes.

To create detached triggers:

1. Create a handle using `new Tooltip.Handle<Payload>()`
2. Attach the same handle to multiple `Tooltip.Trigger` components
3. Each trigger provides a `payload` prop containing a content snippet
4. Use a single `Tooltip.Root` component with the handle to render the popup

<ComponentPreview name="p-tooltip-3" />


---

## Document: useMediaQuery

# useMediaQuery

> Reactive media query helper with Tailwind-like syntax.

[Canonical documentation](https://coss-sv.vercel.app/docs/hooks/use-media-query)

A Svelte helper that creates a reactive, SSR-safe media query. It builds on Svelte's `MediaQuery`
class and preserves the Tailwind-like shorthand from COSS.

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/use-media-query.json" />

## Usage

### Breakpoint shorthand

Use Tailwind variant syntax to match breakpoints. TypeScript provides full autocomplete. Read the
reactive result through `.current`.

```svelte
<script lang="ts">
  import { useMediaQuery } from "$lib/hooks/use-media-query.svelte.js";

  // Min-width (breakpoint and above) — like md:
  const isDesktop = useMediaQuery("md");

  // Max-width (below breakpoint) — like max-md:
  const isMobile = useMediaQuery("max-md");

  // Range (between two breakpoints) — like md:max-lg:
  const isTablet = useMediaQuery("md:max-lg");
</script>
```

### Object API

Use the object form when you need pointer detection or custom pixel values.

```ts
// Touch device detection
const isTouch = useMediaQuery({ pointer: "coarse" });

// Breakpoint + pointer combined
const isMobileTouch = useMediaQuery({ max: "md", pointer: "coarse" });

// Custom pixel values
const isNarrow = useMediaQuery({ max: 600 });
```

### Raw media query

Pass any valid CSS media query string as an escape hatch.

```ts
const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");
const prefersReducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
```

### Conditional rendering

The primary use case is mounting one component instead of another based on the viewport.

```svelte
<script lang="ts">
  import { useMediaQuery } from "$lib/hooks/use-media-query.svelte.js";

  const isDesktop = useMediaQuery("lg");
</script>

{#if isDesktop.current}
  <DesktopNav />
{:else}
  <MobileNav />
{/if}
```

## Breakpoints

The helper includes a static breakpoint map that must match your Tailwind config. Default values:

| Name  | Value  |
| ----- | ------ |
| `sm`  | 640px  |
| `md`  | 800px  |
| `lg`  | 1024px |
| `xl`  | 1280px |
| `2xl` | 1536px |
| `3xl` | 1600px |
| `4xl` | 2000px |

If you override breakpoints in your Tailwind CSS `@theme`, update `BREAKPOINTS` in the helper to
match.

## API

```ts
function useMediaQuery(query: BreakpointQuery | MediaQueryInput | string): MediaQuery;
```

### String queries

| Pattern           | Example                          | Matches                  |
| ----------------- | -------------------------------- | ------------------------ |
| `"{bp}"`          | `"md"`                           | Viewport ≥ breakpoint    |
| `"max-{bp}"`      | `"max-md"`                       | Viewport &lt; breakpoint |
| `"{bp}:max-{bp}"` | `"md:max-lg"`                    | Between two breakpoints  |
| `"(...)"`         | `"(prefers-color-scheme: dark)"` | Raw CSS media query      |

### Object queries

| Property  | Type                   | Description                                               |
| --------- | ---------------------- | --------------------------------------------------------- |
| `min`     | `Breakpoint \| number` | Min-width breakpoint name or pixel value                  |
| `max`     | `Breakpoint \| number` | Max-width breakpoint name or pixel value                  |
| `pointer` | `"coarse" \| "fine"`   | Pointer type (`coarse` for touch, `fine` for mouse input) |

### Return value

Returns a reactive Svelte `MediaQuery`. Its `.current` property is `true` when the query matches and
`false` otherwise. The server fallback is `false`.

## Examples

Resize the viewport to see values update in real time.

<MediaQueryDemo />

## Convenience export

The helper also exports `useIsMobile` for parity with COSS and shadcn's `use-mobile` pattern:

```svelte
<script lang="ts">
  import { useIsMobile } from "$lib/hooks/use-media-query.svelte.js";

  const isMobile = useIsMobile(); // equivalent to useMediaQuery("max-md")
</script>
```


---

## Document: useCopyToClipboard

# useCopyToClipboard

> Copy text to the clipboard with temporary copied feedback.

[Canonical documentation](https://coss-sv.vercel.app/docs/hooks/use-copy-to-clipboard)

A Svelte utility that wraps the Clipboard API and resets its copied state after a timeout. It is
useful for copy buttons that briefly confirm success.

## Installation

<InstallCommand shadcnSvelte="pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/use-copy-to-clipboard.json" />

## Usage

### Basic

```svelte
<script lang="ts">
  import { useCopyToClipboard } from "$lib/hooks/use-copy-to-clipboard.svelte.js";

  let { text }: { text: string } = $props();
  const clipboard = useCopyToClipboard();
</script>

<button onclick={() => clipboard.copyToClipboard(text)} type="button">
  {clipboard.isCopied ? "Copied!" : "Copy"}
</button>
```

### Custom timeout

`isCopied` resets after two seconds by default. Pass a different duration in milliseconds:

```ts
const clipboard = useCopyToClipboard({ timeout: 3_000 });
```

Set `timeout` to `0` to keep `isCopied` true until the component unmounts.

### Callback on copy

Run a callback after the clipboard write succeeds:

```ts
const clipboard = useCopyToClipboard({
  onCopy: () => console.log("Copied to clipboard"),
});
```

### With icon swap

Swap an icon briefly to confirm the copy:

```svelte
<script lang="ts">
  import Copy01Icon from "@hugeicons/core-free-icons/Copy01Icon";
  import Tick01Icon from "@hugeicons/core-free-icons/Tick01Icon";
  import { Button } from "$lib/components/ui/button/index.js";
  import HugeiconsIcon from "$lib/hugeicons-icon.svelte";
  import { useCopyToClipboard } from "$lib/hooks/use-copy-to-clipboard.svelte.js";

  let { value }: { value: string } = $props();
  const clipboard = useCopyToClipboard();
</script>

<Button
  aria-label="Copy to clipboard"
  onclick={() => clipboard.copyToClipboard(value)}
  size="icon"
  variant="outline"
>
  <HugeiconsIcon
    aria-hidden="true"
    icon={clipboard.isCopied ? Tick01Icon : Copy01Icon}
    strokeWidth={2}
  />
</Button>
```

## API

```ts
function useCopyToClipboard(options?: { timeout?: number; onCopy?: () => void }): {
  copyToClipboard: (value: string) => void;
  readonly isCopied: boolean;
};
```

### Options

| Property  | Type         | Default | Description                                                          |
| --------- | ------------ | ------- | -------------------------------------------------------------------- |
| `timeout` | `number`     | `2000`  | Milliseconds before copied feedback resets. Use `0` to keep it true. |
| `onCopy`  | `() => void` | —       | Called after a successful clipboard write.                           |

### Return value

| Property          | Type                      | Description                                                     |
| ----------------- | ------------------------- | --------------------------------------------------------------- |
| `copyToClipboard` | `(value: string) => void` | Copies non-empty text when the Clipboard API is available.      |
| `isCopied`        | `boolean`                 | True until the configured timeout ends after a successful copy. |