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, font variables, and base styles. Components like Dialog and AlertDialog use font-heading for titles—the style preset provides sensible fallbacks, and you can customize fonts via next/font in your layout.

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.

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:

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