Documentation

Getting started

From an empty project to a themed UI in five steps: install, wrap your app, add a component, theme it, and drop in a block.

Browse components

1. Install

Run init inside your project. The CLI is framework-agnostic and acts on the current directory — it writes cooud-ui.json, installs base dependencies, imports the tokens stylesheet, and wires the provider and config for you.

bash

npx cooud-ui@latest init

Prefer another package manager? Use pnpm dlx cooud-ui@latest init, yarn dlx cooud-ui@latest init, or bunx cooud-ui@latest init. Adding Cooud UI to an app you already have? See Installation.

2. Wrap your app with the provider

Import the tokens stylesheet once, then wrap the app in CooudUIProvider at the framework root so every component shares the same theme.

tsx

import "@cooud-ui/tokens/styles.css";
import { CooudUIProvider } from "@cooud-ui/theme";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <CooudUIProvider asRoot defaultThemeName="aurora" defaultModeName="dark">
          {children}
        </CooudUIProvider>
      </body>
    </html>
  );
}

Put it at the root

The provider belongs at the very top of your tree — the layout in Next.js, the root route in TanStack Start or React Router, or wherever your app mounts. To avoid a flash of the wrong theme on returning visitors, also render CooudThemeScript in the document head so the saved mode applies before paint. See Theming for the full no-FOUC setup.

3. Add your first component

Copy a component into your app with add. The CLI writes the source and rewrites its imports to your local aliases, so you import it from your own components folder.

bash

npx cooud-ui add button

This writes components/ui/button.tsx. Import it and render it — it's already styled by the tokens the provider supplies.

tsx

import { Button } from "@/components/ui/button";

export default function Page() {
  return (
    <main className="flex min-h-svh items-center justify-center bg-surface-base">
      <Button>Get started</Button>
    </main>
  );
}

4. Theme it

Theme is a design-system object — colors, brand accents, fonts, and radius move together. Flip light and dark at runtime with the useTheme hook, which reads and persists the active mode through the provider.

tsx

"use client";

import { Button } from "@cooud-ui/ui";
import { useTheme } from "@cooud-ui/theme";
import { Moon, Sun } from "lucide-react";

export function ModeToggle() {
  const { mode, toggleMode } = useTheme();
  const isDark = mode === "dark";

  return (
    <Button
      variant="outline"
      size="icon"
      onClick={toggleMode}
      aria-label={isDark ? "Switch to light mode" : "Switch to dark mode"}
    >
      {isDark ? <Sun aria-hidden="true" /> : <Moon aria-hidden="true" />}
    </Button>
  );
}

Swap whole presets, override individual tokens at runtime, or build a look visually in Create. See Theming and Styling for the full API.

5. Drop in a block

A component is a single primitive; a block is a whole section composed from primitives — a login screen, a pricing grid, a dashboard. Add one with the same command, then render it.

bash

npx cooud-ui add login

This writes components/blocks/login.tsxand installs the block's dependencies. The file is yours — edit the copy, swap the data, restyle with tokens.

tsx

import { LoginBlock } from "@/components/blocks/login";

export default function SignInPage() {
  return (
    <main className="flex min-h-svh items-center justify-center bg-surface-base p-6">
      {/* Installed source — yours to edit, restyle, and wire up. */}
      <LoginBlock />
    </main>
  );
}

Browse blocks

Where to go next

You have a themed app with a component and a block. Here is where to deepen each part.

Components

Browse the full catalog of primitives, with live previews and props.

Browse components

Blocks

Composed sections — auth, dashboards, pricing — ready to drop into a page.

Read about blocks

Theming

Tokens, presets, runtime overrides, and flash-free dark mode.

Theme the system

Recipes

Copy-paste patterns: validated forms, toasts, confirmations, and more.

Read recipes

CLI

init, add, list, and diff — the full registry command surface.

Read CLI docs