Base UI Support

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

Selecting Your UI Library

You can switch between Radix UI and Base UI blocks using the dropdown next to the shadcn CLI install command. This dropdown appears in both the Explorer and on individual block pages.

When you change your selection:

1. Preview — See how blocks render with your chosen library
2. CLI command — The copy button generates the correct installation command
3. components.json export — Downloads are configured for your selected library

Your preference is remembered across sessions, so you only need to set it once.

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. However there are some breaking changes between Radix UI and Base UI that require updated (base-ui specific) versions of our blocks.

Known Compatibility Issues

The main compatibility challenge between Radix UI and Base UI involves the asChild prop pattern.

What is asChild?

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
<Button asChild>
  <a href="/about">About</a>
</Button>

Radix UI and Base UI handle this differently:

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

Simple Button Links

Many of our blocks use <Button asChild> to wrap links. When installed with Base UI, these will still work but produce unsemantic HTML like <button><a>...</a></button>. To fix this, replace asChild with the render prop:

// Before (Radix pattern)
<Button asChild>
  <a href="/about">About</a>
</Button>

// After (Base UI pattern)
<Button render={<a href="/about" />}>
  About
</Button>

Complex Components with Base UI-Specific Versions

Some blocks use asChild in more complex ways that require dedicated Base UI versions. These blocks have been rewritten to use the render prop pattern throughout:

• application-shell1 through application-shell14
• sidebar1 through sidebar21
• chart-group11 through chart-group15

To install the Base UI-specific version, use the base/ path prefix in the registry:

npx shadcn@latest add @shadcnblocks/base/application-shell1

Note the base/ segment after @shadcnblocks/. This tells the CLI to fetch from our Base UI-specific registry, which contains blocks rewritten to use the render prop pattern instead of asChild.

Registry Path Format

Path	Description
@shadcnblocks/hero1	Standard block (works with both, may have asChild)
@shadcnblocks/base/sidebar1	Base UI-specific version (uses render prop)

The Base UI-specific versions are only needed for complex blocks where the asChild pattern is deeply integrated. For simple blocks with just a few <Button asChild> instances, you can either use the standard version and update those instances yourself, or report the issue so we can create a Base UI-specific version.

Next Steps

• Component Styles — Learn about the available visual styles
• Explorer Guide — Master the Explorer’s features
• Getting Started — Complete installation guide