Get Started

This guide provides the essentials for adding coss ui components to your React application.

Prerequisites

Our components are built with Tailwind CSS v4. Before you begin, make sure you have a React project set up with Tailwind CSS.

Adding Components

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

With the CLI

Each component page provides a command to add it to your project automatically. The CLI will create the necessary files and install any dependencies for you.

New Project Setup (Recommended)

For new projects, use the coss style preset to initialize everything in one command:

bunnpmpnpmyarn
pnpm dlx shadcn@latest init @coss/style
Copy

This installs all UI components, the neutral color system, sidebar variables, and base styles. It also installs Inter (--font-sans, --font-heading) and Geist Mono (--font-mono) as default fonts, automatically configured in your layout.tsx.

Existing Projects

To add components to an existing project:

bunnpmpnpmyarn
pnpm dlx shadcn@latest add @coss/ui
Copy

This adds all UI primitives (button, card, avatar, dialog, tabs, and more). For the full theme including colors, sidebar, and fonts:

bunnpmpnpmyarn
pnpm dlx shadcn@latest add @coss/style
Copy

Or add only the color tokens:

bunnpmpnpmyarn
pnpm dlx shadcn@latest add @coss/ui @coss/colors-neutral
Copy

See the Styling guide for more details.

Manually

1. Find a component on the Components or Particles pages.
2. Copy the code from the Code tab.
3. Create a new file in your project (e.g., components/ui/button.tsx) and paste the code.
4. Install any dependencies listed on the component's page.
5. Import and use the component in your app.

Styling

Components are styled with the design token system we use at Cal.com, which is defined by CSS variables and implemented with Tailwind CSS.

The variables are the same as shadcn/ui, and are fully customizable. You can modify them in your global stylesheet (e.g., app/globals.css) to match your design system.

We've introduced a few additional tokens to provide more granular control:

• --destructive-foreground: Used for destructive-outline buttons, destructive menu items, badges, and field errors
• --info and --info-foreground: Commonly used for info-colored badges, toast types, and alerts
• --success and --success-foreground: Used for success-colored badges, toast types, and alerts
• --warning and --warning-foreground: Used for warning-colored badges, toast types, and alerts

Important: If you manually import components, you must also import these additional tokens in your CSS file (e.g., app/globals.css). However, if you use the CLI to import components, these tokens will be automatically imported and configured for you.

Fonts

coss components use three CSS custom properties for typography:

• --font-sans — Body text, buttons, labels, and most UI elements
• --font-mono — Code blocks, <kbd>, monospace text
• --font-heading — Dialog and AlertDialog titles (defaults to Inter, same as --font-sans)

When you use @coss/style, @coss/fonts is installed automatically — Inter for --font-sans and --font-heading, Geist Mono for --font-mono — all wired in your layout.tsx.

Custom fonts

To use different fonts, ensure the variable option in your next/font configuration matches the expected CSS variables:

Copyimport { Inter } from "next/font/google";
import { JetBrains_Mono } from "next/font/google";
 
const inter = Inter({ variable: "--font-sans", subsets: ["latin"] });
const interHeading = Inter({ variable: "--font-heading", subsets: ["latin"] });
const jetbrainsMono = JetBrains_Mono({ variable: "--font-mono", subsets: ["latin"] });

Note: Next.js starters default to variable names like --font-geist-sans, which don't match coss's expected --font-sans. If fonts appear broken after setup, check that the variable names match.

Primitive exports

Components that wrap Base UI primitives re-export the underlying primitive. Use the styled component when our defaults work, or the primitive when you need different compositions or styling. In a monorepo with a shared UI package, apps import from that package—Base UI stays in one place, no need to add it to each app.

Copyimport { Slider, SliderValue, SliderPrimitive } from "@coss/ui/components/slider";

Base UI Re-exports

When you only need useRender, mergeProps, CSPProvider, or DirectionProvider, import them from @coss/ui/base-ui/* instead of adding @base-ui/react as a direct dependency:

• @coss/ui/base-ui/use-render
• @coss/ui/base-ui/merge-props
• @coss/ui/base-ui/csp-provider
• @coss/ui/base-ui/direction-provider

This is especially useful in monorepos: apps and packages that already depend on @coss/ui can use these utilities without adding @base-ui/react as another dependency. You avoid duplicate installs, keep versions in sync, and simplify your dependency tree—@base-ui/react lives in one place (@coss/ui), and everything else imports through it.

Migration from Radix UI

For developers migrating from Radix UI, many of our UI primitives include instructions and examples for translating equivalent Radix components to Base UI. This ensures a smooth transition while preserving accessibility, behaviors, and API patterns.

Working with LLMs

We structure the documentation to make the components AI-friendly, so language models can understand, reason about, and modify them. To support this, we include:

• Agent Skills — Install coss knowledge directly into your AI assistant with npx skills add cosscom/coss. Covers all 53 primitives, styling conventions, migration patterns, and particle examples.
• A llms.txt file that provides a map of the documentation and component structure for your AI agent.
• A Copy Markdown button on every page, so you can easily share content or feed it to your AI workflows.