CLI

We use the shadcn CLI to install components from the Redpanda UI Registry.

Prerequisite as of the Base UI release — install @base-ui/react in your app before running shadcn add. The registry components import from @base-ui/react@^1.4.0 and the compat shim auto-installs alongside them, but the peer dep itself must be present in your package.json:

bun add @base-ui/react@^1.4.0
# npm install @base-ui/react@^1.4.0
# pnpm add @base-ui/react@^1.4.0

Upgrading from a pre-Base UI registry release? See the Upgrading to Base UI guide.

Configuration

NOTE: You only need to do this once.

1. Create a `components.json` file

Create a components.json file at the root of your application or project:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components/redpanda-ui",
    "utils": "@/components/redpanda-ui/lib/utils",
    "ui": "@/components/redpanda-ui",
    "lib": "@/components/redpanda-ui/lib",
    "hooks": "@/components/redpanda-ui/lib"
  },
  "iconLibrary": "lucide",
  "registries": {
    "@redpanda": "https://redpanda-ui-registry.netlify.app/r/{name}.json"
  }
}

Adjust the aliases paths if your project uses a different base directory for UI components.

2. Install and configure Tailwind CSS

The UI Registry uses Tailwind CSS for styling. You'll need to configure the Tailwind compiler in your project.

bun add tailwindcss tw-animate-css
bun add @tailwindcss/postcss -D

Then, create a postcss.config.mjs file at the root of your application or project.

export default {
  plugins: {
    '@tailwindcss/postcss': {
      content: ['./src/**/*.{js,ts,jsx,tsx}'],
    },
  },
};

3. Import the UI registry styles

bunx shadcn@latest add @redpanda/theme

Create a globals.css file within your project's src directory and add the following:

@import "./components/redpanda-ui/style/theme.css"; /* or wherever your aliases point + /style/theme.css */
@import "tailwindcss";
@import "tw-animate-css";

It's important that you add these imports in this order.

4. Wrap your app in `RedpandaProvider`

Most registry components rely on a few cross-cutting providers — theme management, a motion/react MotionConfig, and a global Sonner toaster. The registry ships these pre-wired as the Redpanda Provider. Install it once and mount it near the root of your app:

bunx shadcn@latest add @redpanda/redpanda-provider

import { RedpandaProvider } from "@/components/redpanda-ui/components/redpanda-provider";

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

RedpandaProvider defaults motion/react to reducedMotion="user", which makes registry components honor the OS-level prefers-reduced-motion setting. Without it, motion's default is "never" and animations always play, even for users who have asked for reduced motion.

add

Use the add command to add components and dependencies to your project.

bunx shadcn@latest add @redpanda/button

You can add as many components as you want:

bunx shadcn@latest add @redpanda/card @redpanda/accordion @redpanda/calendar

update

Use add with --overwrite to update components to the latest version:

bunx shadcn@latest add @redpanda/button --overwrite

Update everything at once

The registry ships a meta item called @redpanda/all that depends on every component, hook, and style. Installing it reinstalls the entire registry:

bunx shadcn@latest add @redpanda/all --overwrite

See the interactive Install page to cherry-pick a subset instead.

diff

Use diff to see what changed in a component since you installed it:

bunx shadcn@latest diff @redpanda/button

view

Preview a component's code before installing:

bunx shadcn@latest view @redpanda/button

search

Search for components in the registry:

bunx shadcn@latest search --query "form"

Migrating from fumadocs/cli

If you previously used @fumadocs/cli with a cli.json file, run the migration script:

bash <(curl -fsSL https://redpanda-ui-registry.netlify.app/migrate.sh) --cwd .

The script reads your existing cli.json, generates components.json with the correct aliases and @redpanda registry, deletes cli.json, and prints reinstall commands for all detected components.

Or migrate manually:

Create components.json as shown above (use your existing cli.json baseDir to set the aliases paths)
Delete cli.json
Install new components with bunx shadcn@latest add @redpanda/<name> instead of bunx @fumadocs/cli add --dir ...

Your existing installed component files will continue to work as-is. No changes needed to already-installed code.