How shadcn/ui Works and When It Beats MUI or Chakra

shadcn/ui copies component source into your repo instead of installing a package. How it works now: Base UI, eight styles, theme tokens, Figma kits, vs MUI.

Updated 12 min read
Laptop screen showing HTML code in an editor

shadcn/ui is an open-source set of React components that a CLI copies into your codebase as editable source, instead of shipping them inside an npm package. It sits on headless primitives from Base UI, Radix or React Aria and styles them with Tailwind CSS. Its own docs put it bluntly: it is "how you build your component library."

That model explains much of its reach. The shadcn CLI pulls 7.4 million weekly downloads on npm as of November 2026. This year alone brought a new default primitive library, a third base, eight visual styles and an agent-focused toolkit.

This guide covers how the copy-in model works, how theming and styles fit together, what designers get in Figma, and when shadcn/ui beats a packaged library like MUI or Chakra UI.

Key Takeaways

  • shadcn/ui is a code distribution system: the CLI writes component files into your repo, so you edit button.tsx directly instead of overriding a package.
  • Since July 2026, new projects default to Base UI. Radix is still supported with -b radix, and React Aria became a third base the same month.
  • Theming runs on CSS variables in semantic pairs (primary and primary-foreground), while eight styles (Vega to Sera) change spacing, geometry and density.
  • Every Figma kit listed in the official docs is community-made, so pick one that ships variables for the style you use.
  • Choose shadcn/ui when you want to own your design system. Choose MUI or Mantine when you want a maintained package with a long component list and no code to own.

New UI kits, design system teardowns and component libraries land in the UI Things newsletter every week.

What Is shadcn/ui?

shadcn/ui is "a set of beautifully-designed, accessible components and a code distribution platform," according to its introduction page. The same page adds the line most people remember: "This is not a component library. It is how you build your component library."

A traditional library ships compiled components inside node_modules. When a button needs a different focus ring or an extra variant, you wrap it, override its styles or fork the package. With shadcn/ui, you get the component source instead, so the change happens in a file your team already reviews in pull requests.

shadcn/ui homepage with component previews

Who Builds It

The project was created by the developer known as shadcn, who builds it at Vercel. It launched in January 2023 on top of Radix primitives, and the GitHub repository is MIT licensed.

The repository shows 128k stars in the site header as of November 2026. Stars do not measure installs, but they show how many developers follow the project.

Why shadcn/ui Matters in 2027

Two shifts made shadcn/ui more relevant. The first is AI-assisted coding: the docs list "AI-Ready" as a core principle because open code is something a model can "read, understand, and improve." One r/reactjs developer notes that most AI tools produce React and shadcn components first, which helps explain why so many prototypes look alike.

The second is design systems moving into code. On r/UXDesign, designers ask how urgently they need to manage the design system directly in the codebase. For many teams, shadcn/ui is where that codebase starts.

How shadcn/ui Works: The Copy-In Model

The model has three layers: a CLI that copies files, primitives that handle behavior, and Tailwind classes that handle the look. Each layer is replaceable, which is the whole point.

The CLI Copies Source, Not a Package

You run one command and the component's TypeScript source lands in your project, usually under components/ui/. From then on, the markup, classes and variants are yours to edit.

Shell
pnpm dlx shadcn@latest init
pnpm dlx shadcn@latest add button card dialog

The CLI reference also covers view, search, apply, docs, info, build and migrate. The components.json file stores your setup, and the docs note it is only required when you use the CLI. Its style value cannot be changed after initialization, so choose deliberately.

Primitives Handle Behavior

Keyboard navigation, focus management and screen reader support come from a headless library that still installs from npm. Since July 2026, npx shadcn init picks Base UI by default. The team cited Base UI reaching version 1.6.0 and projects on shadcn/create choosing Base UI over Radix "2 to 1."

Radix was not deprecated. The changelog says every update and new component ships for both libraries, unless a component exists only in Base UI, and that working Radix apps do not need to migrate. React Aria joined as a first-class base on July 17, 2026.

Shell
pnpm dlx shadcn init -b radix
pnpm dlx shadcn@latest init --base aria

Tailwind Handles the Look

Tailwind CSS is a hard requirement. Each component is a set of utility classes plus variants, and since September 2026 every component imports a cn helper from its own cn package instead of a hand-written lib/utils.ts. Older projects can switch with shadcn migrate cn.

The Tailwind v4 update moved colors from HSL to OKLCH, removed forwardRef, and added a data-slot attribute to every primitive for styling. Existing Tailwind v3 and React 18 apps keep working.

What Owning the Code Costs

npm update never touches copied files. When upstream fixes a bug, you decide whether to pull it in, and the fix can conflict with your own edits.

One r/reactjs commenter summed up the trade: "Shadcn is a starter kit for a design system that you maintain." (u/nayeem14 in r/reactjs, late 2025). Another in the same thread put it shorter: "I'm my own maintainer."

Installing shadcn/ui in a New or Existing Project

The installation docs recommend shadcn/create for new projects. You build a preset visually, preview it, and copy a setup command for your framework.

shadcn/ui installation docs recommending shadcn/create

Supported Frameworks

shadcn/create generates setups for Next.js, Vite, Laravel, React Router, Astro and TanStack Start. From the terminal, init -t scaffolds the next, vite, start, react-router and astro templates.

Shell
pnpm dlx shadcn@latest init -t next

Laravel is the exception: create the app with laravel new first, then run init. For an existing app, each framework guide has a manual section.

Adding Components and Blocks

shadcn add installs single components. Blocks are larger compositions, such as dashboards, sign-in pages and sidebars, that copy several files at once.

Registries extend this beyond the official set. Any team can run its own registry for components, hooks, pages or config, and it works with any framework. Since August 2026, the CLI can also install from private GitHub repositories using your existing gh login.

Third-Party Registries

The registry directory lists community registries built into the CLI, installed as npx shadcn add @<registry>/<component>. The docs warn that these are maintained by third parties, so review the code on install. Treat a registry item like a pull request from a stranger.

Theming shadcn/ui: Tokens, Base Colors and Styles

shadcn/ui separates three things that many libraries blur: color tokens, base colors and styles.

Semantic Color Tokens

The theming docs recommend CSS variables, which is the default (tailwind.cssVariables: true). Tokens come in pairs: the base token sets the surface, and the -foreground token sets text and icons on that surface.

Token

Controls

Used by

background / foreground

Default app surface and text

Page shell, sections

primary / primary-foreground

High-emphasis actions

Default Button, active states

muted / muted-foreground

Subtle surfaces and helper text

Descriptions, placeholders

accent / accent-foreground

Hover, focus and selected surfaces

Ghost buttons, menu highlights

destructive

Destructive actions and errors

Delete buttons, invalid states

border, input, ring

Borders, form controls, focus rings

Cards, inputs, focusable controls

chart-1 to chart-5

Chart palette

Charts and dashboard blocks

sidebar set

Sidebar surfaces and states

The Sidebar component

radius

Base corner radius

Cards, inputs, buttons, popovers

shadcn/ui theme tokens and what they control

To add a token, define it under :root and .dark, then expose it to Tailwind with @theme inline:

CSS
:root {
  --warning: oklch(0.84 0.16 84);
  --warning-foreground: oklch(0.28 0.07 46);
}

@theme inline {
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
}

You can then use bg-warning and text-warning-foreground in any component.

Radius and Base Colors

One --radius value drives a whole scale. radius-lg equals the base, radius-sm is 0.6 times it, and radius-4xl is 2.6 times it, so changing one variable reshapes every corner.

The baseColor setting picks the neutral palette generated at init. The options are Neutral, Stone, Zinc, Mauve, Olive, Mist and Taupe.

Eight Styles Change Geometry, Not Color

A style rebuilds the same components with different padding, control heights, corners and density. The eight styles are Vega, Nova, Maia, Lyra, Mira, Luma, Rhea and Sera, and each works with Base UI, Radix and React Aria.

Two recent ones show the range. Sera (April 2026) is typography-first, with serif headings, square corners and underlined controls. Rhea (May 2026) is "a more compact Luma" for dense product UIs.

The team built Rhea as a new style because changing Tailwind's --spacing multiplier would change what p-2 means across your app.

In components.json, the library and style are stored together, such as base-nova. Presets bundle a style, base color, theme, fonts and icons into a short code you apply with shadcn apply.

shadcn/ui in Figma: What Designers Should Know

The Figma page in the official docs opens with a caveat: "The Figma files are contributed by the community." There is no first-party kit, so the kit you pick decides how close design stays to code.

Free Kits

The docs list four free files. The oldest, Pietro Schirano's design system, shows 364k users on Figma Community, yet its comment thread includes "This is a kit, not a design system. No tokens" and "Needs variables."

Newer free options close that gap. The docs describe the shadcncraft Free Starter Kit as having native Figma variables for all eight styles, and Obra Studio's Community Edition as having an easy theming system.

Eight paid kits are listed, including shadcn/ui kit by Matt Wierzbicki, Obra shadcn/ui Pro, shadcn/studio and Shadcnblocks. Most add blocks, templates and design-to-code export.

How to Choose a Kit

Match three things before you commit. The kit should support your style (a Vega kit will mislead a Rhea codebase), map colors to variables that use the same token names as your CSS, and stay maintained as new components ship. For a broader list of starting points, see our roundup of free Figma UI kits.

shadcn/ui vs MUI, Chakra UI and Mantine

The decision comes down to ownership: does your team want to maintain its component code, or install someone else's?

Library

How you get it

Styling

Price

Best for

shadcn/ui

CLI copies source into your repo

Tailwind CSS, CSS variables, 8 styles

Free, MIT

Teams building their own design system

Material UI

npm package

Material Design 2, theme object

Free core; MUI X from $299 per developer

Data-heavy apps that need advanced grids

Chakra UI

npm package

Tokens and recipes

Free

Teams wanting a themeable package with tokens

Mantine

npm package

Native CSS with a Styles API

Free

Apps that need 120+ components and 70+ hooks out of the box

shadcn/ui compared with packaged React libraries

When shadcn/ui Wins

Pick shadcn/ui when your product needs a distinct look, when designers and developers share a token system, or when AI agents generate much of your UI. Copied code is easy for a model to read, and the shadcn skill feeds your components.json setup to tools like Claude Code.

It also wins when a library's gaps would force workarounds. One r/reactjs commenter at a MUI shop described wrapping a shadcn dropdown to get a nested menu MUI lacked, then accepting that bugs in that code were now theirs.

When a Packaged Library Wins

Pick MUI when you need advanced components such as Data Grid Pro, sold through MUI X licenses priced per developer (Pro $299, Premium $599, Enterprise $1,399). Pick Mantine when you want 120+ components and 70+ hooks maintained for you.

A packaged library also suits small teams without a designer, who benefit from someone else's defaults and release notes. If you already run a React kit like Untitled UI React, compare its component coverage before switching.

What Changed in shadcn/ui During 2026

If your mental model is Radix plus Tailwind plus copy-paste, the changelog shows how much has been added since late 2025.

Date

Change

December 2025

npx shadcn create lets you pick library, icons, base color, theme and fonts

March 2026

shadcn/cli v4 and the Luma style

April to May 2026

Sera and Rhea styles, presets, shadcn apply

June 2026

Chat components: MessageScroller, Message, Bubble, Attachment, Marker

July 2026

Base UI becomes the default, React Aria base, shadcn/typeset

August 2026

Private GitHub registries, Questionnaire component

September 2026

cn moves into its own package

October 2026

Trace, Code Block and 21 AI Elements patterns

UI SDK: Behaviors for Agents

On November 12, 2026, Vercel Labs released UI SDK, a TypeScript library of more than 50 UI behaviors such as roving focus, typeahead and popups. It is in beta and ships ready-made components for React, Vue, Svelte, Solid and Web Components.

UI SDK announcement page

shadcn framed the release on X: "Agents are becoming both the builders and the users of interfaces. So we asked ourselves: where should the abstraction live?" (shadcn (@shadcn), November 2026). UI SDK sits a layer below shadcn/ui, in the behavior code that agents compose into components.

Common shadcn/ui Mistakes to Avoid

Shipping the Default Theme Unchanged

Untouched default settings are the look many people now call "AI-generated." As u/bogdanelcs put it in r/Frontend: "Vibe-coded frontends look AI because they use default everything" (June 2026). Pick a style, base color and fonts in shadcn/create before writing product code.

Treating Copied Code Like a Dependency

Teams that never read their components/ui/ folder miss upstream fixes and security reviews. Schedule a check of the changelog and use the CLI's migrate commands, such as migrate cn, instead of hand-patching dozens of files.

Ignoring Primitive Health

The Radix version of the Drawer is still built on Vaul, whose README says the repo is unmaintained. The Base UI Drawer replaced Vaul. Check which primitive each component depends on before you build on it.

Picking a Style You Cannot Change

The style field in components.json is fixed after init. Settle on Rhea, Sera or another style during setup, not three sprints in.

Mixing Token Names Between Figma and Code

If your Figma kit calls a color brand/500 while your CSS calls it --primary, every handoff needs translation. Use the same semantic names (primary, muted, accent) in both places. Our guide to design systems covers token naming in more depth.

shadcn/ui in Practice: Building on the Copy-In Model

CopilotKit's open-source Shadify shows where the model leads. A LangChain agent composes shadcn components on the fly from a description, and the result can be exported as React code (CopilotKit on X, March 2026).

The move to Base UI followed the same ownership idea. Rather than swap libraries under existing apps, the team rebuilt every component for Base UI and let users choose. Usage then tipped toward Base UI before it became the default, so the default followed user behavior instead of forcing it.

For design engineers, the practical lesson is to treat shadcn/ui as a scaffold. Use it to get accessible behavior and a coherent token system on day one, then make the components yours. Our design engineering guide covers the role that usually owns this work.

Frequently Asked Questions

Related Articles