Installation

Prerequisites

• React 18+ or 19
• Tailwind CSS v4
• TypeScript (recommended)

Setup

1. Initialize shadcn

If you haven't already, initialize shadcn in your project:

npx shadcn@latest init

2. Add the Saturation UI registry

Add the registry to your components.json so the CLI knows where to find Saturation UI components and blocks:

{
  "registries": {
    "@saturation-ui": "https://ui.saturation.io/r/{name}.json"
  }
}

3. Install components

Install any component using the @saturation-ui/ prefix:

npx shadcn@latest add @saturation-ui/button

The CLI will automatically install the component, its npm dependencies, and any required peer components.

Install blocks using the @saturation-ui/ prefix:

npx shadcn@latest add @saturation-ui/login

You can also install by direct URL (no registry config required):

npx shadcn@latest add https://ui.saturation.io/r/button.json
npx shadcn@latest add https://ui.saturation.io/r/login.json

Install the full design system

To bootstrap all CSS variables, fonts, and base config in one command:

npx shadcn@latest add @saturation-ui/saturation-base

Install fonts

Saturation UI uses Inter (sans-serif) and Geist Mono (code). Install them as registry items:

npx shadcn@latest add @saturation-ui/font-inter
npx shadcn@latest add @saturation-ui/font-geist-mono

CLI Tips (shadcn v4)

Preview before installing

Use --dry-run to see exactly what will be added to your project before any files are written:

npx shadcn@latest add @saturation-ui/button --dry-run

Check for updates

Use --diff to see what changed between your current version and the latest registry version:

npx shadcn@latest add @saturation-ui/button --diff

Inspect the payload

Use --view to see the raw component payload without installing:

npx shadcn@latest add @saturation-ui/button --view

Project info

Run shadcn info to see your full project setup — framework, installed components, CSS vars:

npx shadcn@latest info

Docs in the terminal

Get docs, API, and examples for any component right in your terminal:

npx shadcn@latest docs button

Manual Installation

If you prefer to install components without the CLI:

1. Copy the component source from the docs page
2. Install the required npm dependencies listed on the component page
3. Place the file in your components/ui/ directory
4. Ensure your lib/utils.ts exports the cn() function

Path Aliases

Saturation UI components use the @/ path alias. Ensure your tsconfig.json has:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}