Installation

Cubby UI uses the shadcn CLI to add components to your project. Components are copied directly into your codebase, giving you full ownership and control.

Prerequisites

Before installing components, ensure your project has:

React 19 or later
Tailwind CSS 4 configured
TypeScript

Quick Start

Cubby UI is listed in the official shadcn registry directory, so the @cubby-ui namespace resolves automatically — there's no need to add it to your components.json.

1. Install Base UI

Cubby UI components are built on Base UI, a headless component library:

npm install @base-ui/react

2. Add the theme

Cubby UI ships its theme as a standalone style — @cubby-ui/style — covering colors, status colors, radius, easings, and the surface elevation system. Choose the path that matches your project:

Scaffold shadcn and install Cubby UI's theme as your project's base in a single command:

npx shadcn@latest init @cubby-ui/style

This creates your components.json and writes the full theme into globals.css.

3. Add the root class

Add a root class to your application wrapper. This creates a stacking context required by Base UI's portal-based components:


export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <div className="root">{children}</div>
      </body>
    </html>
  );
}

4. Add components

Now you can add any Cubby UI component:

npx shadcn@latest add @cubby-ui/button

This will:

Copy the component source code to your project
Install any required dependencies
Set up the necessary utility functions

Adding Multiple Components

Add multiple components in a single command:

npx shadcn@latest add @cubby-ui/button @cubby-ui/input @cubby-ui/card

Or install all components at once:

npx shadcn@latest add @cubby-ui/all

The @cubby-ui/style theme adds CSS variables for colors (including status colors), border radius variants, easing functions, the surface elevation system, and Base UI layout requirements. See Theming for full details.

Project Structure

After adding components, your project structure will look like this:


components/
  ui/
    cubby-ui/
      button.tsx
      input.tsx
      card.tsx
hooks/
  cubby-ui/
    use-mobile.ts
lib/
  cubby-ui/
    utils.ts
components.json

The exact paths depend on your components.json configuration.

Manual Installation

If you prefer not to use the CLI, you can manually copy component source code from the documentation and install dependencies yourself. Each component's documentation page includes the full source code and dependency list.

For the theme setup, copy the CSS variables from the Theming guide into your globals.css.

Next Steps

Browse the Components to see what's available
Learn about Theming to customize the look and feel
Check out individual component pages for usage examples