Cubix
GitHub

Installation

Set up Cubix in a new or existing React app. Initialize design tokens and utilities, choose a primitive backend, then add components as source files you own.

Requirements

  • React 18+ (React 19 recommended)
  • Tailwind CSS v4
  • TypeScript (project default)
  • A path alias for @/* pointing at your project root

Cubix works with Next.js, Vite, Remix / React Router, Astro islands, TanStack Start, and other React hosts. See Introduction for framework notes.

Initialize a project

Run init in the root of your app. The CLI writes Cubix tokens into your CSS entry, creates lib/utils.ts with the cn helper, and adds a cubix.json config:

pnpm dlx cubix@latest init

Default base is Base UI. Pass --base aria or --base radix if your team standardizes on React Aria or Radix UI instead.

cubix.json
{
  "$schema": "https://cubix.design/schema.json",
  "style": "cubix",
  "base": "base",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/cubix",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

Add a component

Components are copied into components/cubix from the registry. Install only what you need:

pnpm dlx cubix@latest add button

Override the project base for a single add:

pnpm dlx cubix@latest add button --base radix

Then import from your local path:

components/example.tsx
import { Button } from "@/components/cubix/button"

export function Example() {
  return <Button>Get started</Button>
}

Full CLI reference lives on the CLI page. Browse the catalog under Components.

Choose a base

Cubix keeps one visual API across three accessibility backends. Pick the stack that matches your product; switch per component with --base when needed.

Base UI

base (default)

Default for new Cubix projects.

React Aria

--base aria

When your app already centers on React Aria.

Radix UI

--base radix

When you prefer Radix primitives under Cubix.

Manual setup

Prefer not to use the CLI for bootstrap? Wire the shared pieces by hand, then paste component files from the registry or docs Manual tab.

1. Path alias

Ensure TypeScript (and your bundler) resolve @/*:

tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

2. Core dependencies

Install the packages every Cubix component expects. Tailwind CSS v4 should already be in the project:

pnpm add class-variance-authority clsx tailwind-merge lucide-react

For the default base, also install Base UI:

pnpm add @base-ui/react

Other bases and individual components may need extra packages. The Manual install section on each component page lists them.

3. Utilities and tokens

Add lib/utils.ts:

lib/utils.ts
import { clsx, type ClassValue } from "clsx"
import { extendTailwindMerge } from "tailwind-merge"

const twMerge = extendTailwindMerge({
  extend: {
    theme: {
      text: [
        "display",
        "headline",
        "title",
        "lead",
        "body",
        "caption",
        "label",
      ],
    },
  },
})

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

Copy the Cubix design tokens (oklch light and dark palettes, radius, and related variables) into your global CSS entry - typically app/globals.css. See Theming for the token map.

4. Paste a component

Create components/cubix/button.tsx (or your chosen name), paste the source from the docs or public/r/*.json, install any listed dependencies, and fix import paths if your aliases differ.

Next steps