coss.com Svelte

Get Started

A quick guide to adding your first Svelte component.

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. 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:

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:

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 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:

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:

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 guide for the color tokens, sidebar variables, and base styles.

Manual installation

  1. Find a component on the Components or 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 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:

: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:

: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.

<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 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 with the component catalog, Svelte conventions, and registry workflow used by this port.
  • An 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.