Base UI

Shadcnblocks 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. (A third option, React Aria, works the same way with aria-* styles.)

Note: shadcn/ui now uses Base UI as the default for new projects created with npx shadcn@latest create. Our recommendation is still Radix UI (see below), but every block is available for both, so pick whichever your project already uses.

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 recommended 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. Every Shadcnblocks block is authored against Radix first, and the Base UI and React Aria builds are ports of it, so Radix is the path with the fewest surprises.

When to use Base UI:

Base UI is a good alternative if you prefer smaller bundle sizes or a different API, or if you started a new project with a recent shadcn/ui version, which now defaults to Base UI. 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.

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.). Blocks import those components the same way in both libraries; with a base-* style and the {style} registry URL, the registry serves the block’s Base UI version when one exists. See Primitive libraries for the details.

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
`radix-luma`	Radix UI	Luma
`radix-sera`	Radix UI	Sera
`radix-rhea`	Radix UI	Rhea
`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
`base-luma`	Base UI	Luma
`base-sera`	Base UI	Sera
`base-rhea`	Base UI	Rhea

Getting Started

1. Update Your components.json

Set the style in your components.json to a Base UI style (e.g., base-vega) and make sure the @shadcnblocks registry URL includes the {style} placeholder. A complete example is in Example Configuration below. On any block page you can switch the toolbar’s library menu to Base UI to preview the block and see the matching style value.

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://www.shadcnblocks.com/r/{style}/{name}"  }}

{style} lets the registry serve the Base UI or React Aria version of a block when your components.json style is base-* or aria-*; the older /r/{name} URL keeps working and always serves the Radix version. See Primitive libraries.

Updating Blocks

Most Shadcn Blocks require no changes when switching between Radix UI and Base UI. With a base-* style and the {style} registry URL you get the Base UI version, already authored against the Base wrappers (render instead of asChild, and the other Base API differences).

If you copy/paste the Radix source instead, convert those APIs yourself. The most common difference is asChild → render:

// Radix UI pattern<Button asChild>  <a href="/about">About</a></Button>// Base UI pattern<Button render={<a href="/about" />} nativeButton={false}>  About</Button>

Radix UI uses asChild; Base UI uses render (and nativeButton={false} on Button when the child is not a <button>).