Getting started

Overview

Coloxo uses a copy-source model: the CLI copies components from the registry into your codebase so you own the files. Run init once, then add components by slug.

Every component ships in one or both styles: Coloxo CSS (CSS Modules over semantic design tokens) or Tailwind (flat TSX with the classes inlined). You choose at init with --style, and the same command works for both. See the styling guide for which components support which style.

This site runs on @coloxo/ui 1.0.6. Start it with npm run dev in the playground.

Install

Initialize Coloxo in your React project, then add components. Each add copies source files and registry dependencies into paths defined in coloxo.json.

1# init asks for a style and saves it to coloxo.json2npx coloxo init34# or choose up front: --style coloxo-css | tailwind5npx coloxo init --style tailwind67npx coloxo add button

The style you pick at init becomes the default for every later coloxo add. Pass --style on a single add to override it. Without Tailwind detected in your project, init defaults to Coloxo CSS.

Or install the package and import from @coloxo/ui. This site uses @coloxo/ui 1.0.6.

1npm install @coloxo/ui

1import { Button, ThemeProvider } from "@coloxo/ui";2import "@coloxo/ui/styles.css";

Visuals

Shader and canvas visuals are optional. coloxo init does not install them. Add one slug when you want it. The same command works in a Tailwind project and in a Coloxo CSS project, because every visual ships as Coloxo CSS.

1npx coloxo add vortex2npx coloxo add aurora-mesh-gradient

The CLI copies that effect into your project and adds @coloxo/ui to package.json, so the stylesheet is restored on the next npm install. Import it once:

1import "@coloxo/ui/styles.css";2import { WaveBackground } from "@coloxo/ui/visuals";

ThemeProvider

Wrap your application root so light, dark, and system themes apply via data-cx-theme and persisted preferences.

1import { ThemeProvider } from "@coloxo/ui";2import "@coloxo/ui/styles.css";34export function Providers({ children }: { children: React.ReactNode }) {5  return <ThemeProvider defaultTheme="system">{children}</ThemeProvider>;6}

Peer dependencies

Ensure compatible React versions are installed in the host app.

Run this site

Commands for the documentation site. It renders @coloxo/ui 1.0.6, including the optional visuals entry.