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

1. Set up shadcn/ui

If you haven't already, initialize shadcn/ui for your framework. Follow the official guide for your setup:

2. Install Base UI

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

npm install @base-ui/react

3. Add the Cubby UI registry

Add the Cubby UI registry to your components.json:


{
  "registries": {
    "@cubby-ui": "https://cubby-ui.dev/r/{name}.json"
  }
}

Add the registries field to your existing configuration if it doesn't already exist.

4. Initialize Cubby UI theme

Run the init command to add Cubby UI's theme system to your project:

npx shadcn@latest add @cubby-ui/init

Then 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>
  );
}

5. 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

What's Included in Init

The init command adds CSS variables for colors (including status colors), border radius variants, easing functions, 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.

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