Base UI

Shadcnblocks now supports Base UI as an alternative to Radix UI. This means you can choose which underlying primitive library powers your shadcn/ui components—giving you more flexibility and control over your project’s dependencies.

What is Base UI?

Base UI is a headless component library from the MUI team. Like Radix UI, it provides unstyled, accessible primitives that you can style however you want. Base UI offers:

• Zero styling — Pure logic and accessibility, no CSS to override
• Smaller bundle size — Lightweight primitives with minimal overhead
• Familiar API — Similar patterns to Radix UI for easy migration
• Active development — Backed by the original MUI team with regular updates

Radix UI vs Base UI

Both libraries provide accessible, unstyled primitives. The main differences:

Feature	Radix UI	Base UI
Maintained by	WorkOS	MUI
Bundle size	Larger	Smaller
Component count	More	Growing
Ecosystem	Established	Emerging

When to use Radix UI:

Radix UI is still our preferred choice. It has everything you need and works fine. It’s more stable and battle-tested, with a comprehensive set of primitives and excellent accessibility features. Radix arguably offers a more modern primitive library going forward, and that’s the main reason to use it.

When to use Base UI:

Base UI is a good alternative if you prefer smaller bundle sizes or a different API. Some developers have concerns about Radix UI’s maintenance activity, and Base UI (backed by the MUI team) offers an actively developed alternative with a clear long-term roadmap. It’s newer and cooler.

How It Works

Understanding components.json

The style property in your components.json determines which primitive library the shadcn CLI uses when installing components:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-vega"
}

When you run npx shadcn@latest add button, the CLI reads this configuration and installs the appropriate version of the component—either Radix UI or Base UI based primitives. This applies to the underlying shadcn/ui components (Button, Card, Dialog, etc.), not our blocks themselves. Our blocks simply use these components, so switching libraries is handled at the component level.

The style value follows the format {library}-{style}:

Style Value	UI Library	Visual Style
radix-vega	Radix UI	Vega (New York)
radix-nova	Radix UI	Nova
radix-maia	Radix UI	Maia
radix-lyra	Radix UI	Lyra
radix-mira	Radix UI	Mira
base-vega	Base UI	Vega (New York)
base-nova	Base UI	Nova
base-maia	Base UI	Maia
base-lyra	Base UI	Lyra
base-mira	Base UI	Mira

Getting Started

1. Update Your components.json

Update your components.json with a Base UI style (e.g., base-vega). For convenience, we provide pre-generated components.json files that you can download directly—look for the download button next to the CLI command in both the Explorer and on block pages.

2. Reinstall Your Components

Run the shadcn CLI to overwrite your existing components with the Base UI versions:

npx shadcn@latest add --all --overwrite

This will replace all components in your components/ui folder with the Base UI-based versions.

3. Install Blocks

Use the shadcn CLI to install blocks as usual:

npx shadcn@latest add @shadcnblocks/hero1

The CLI will install:

• The block source code
• Required shadcn/ui components (using your configured library)
• The correct primitive library (@radix-ui/* or @base-ui/*)
• Any other npm dependencies

Example Configuration

Here’s a complete components.json for Base UI with the Vega style:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-vega",
  "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/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "@shadcnblocks": "https://shadcnblocks.com/r/{name}.json"
  }
}

Updating Blocks

Most Shadcn Blocks require no changes when switching between Radix UI and Base UI. The underlying primitives are swapped automatically based on your components.json configuration.

The shadcn CLI also automatically transforms the asChild prop to the Base UI render prop pattern during installation. This means you can install our blocks as-is and the CLI handles the conversion for you.

Copy/Paste vs CLI Installation

If you install blocks using copy/paste instead of the CLI, the automatic asChild transformation will not occur. You’ll need to manually convert any asChild patterns to the render prop pattern.

Understanding the asChild Pattern

The asChild prop allows a component to render its children as the root element instead of its default element. For example, wrapping a link inside a Button:

// Radix UI pattern (what our blocks use)
<Button asChild>
  <a href="/about">About</a>
</Button>

// Base UI pattern (what the CLI transforms it to)
<Button render={<a href="/about" />}>
  About
</Button>

Radix UI and Base UI handle this differently:

• Radix UI uses the asChild prop
• Base UI uses a render prop pattern

When using the shadcn CLI, this conversion happens automatically. If you’re copying code manually, you’ll need to make these changes yourself.

Base UI-Specific Versions

In rare cases where the automatic transformation doesn’t cover edge cases, we provide dedicated Base UI versions. These are hand-written implementations.

To install a Base UI-specific version, add base/ after @shadcnblocks/:

npx shadcn@latest add @shadcnblocks/base/sidebar1