Get Started | COSS for Svelte

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.miel.my/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.miel.my/r/button.json https://coss.miel.my/r/card.json

The CLI can install several registry items in one command:

pnpm dlx shadcn-svelte@latest add https://coss.miel.my/r/avatar.json https://coss.miel.my/r/dialog.json https://coss.miel.my/r/tabs.json

See the Styling guide for the color tokens, sidebar variables, and base styles.

Manual installation

Find the component’s documentation page and open Installation > Manual.
Run the dependency command, then copy each listed .svelte and .ts file to its displayed path under src/lib. The file list includes the component’s local dependencies.
Update the imports if your project uses different aliases, then import the component in your app.

The Code tab beside a preview contains the example that uses the component. To copy an example from the docs or View code on the Particles page, install its components first, then copy the example into a separate .svelte file. Its imports identify the component modules and any additional package dependencies it needs.

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 aria-label="Volume" defaultValue={40} />

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 documentation page for sharing its exact content with a coding agent.