shadcn/ui explained: 25 things you need to know in 2026
Published 25 min read
On this page
shadcn/ui is a collection of React components that you don't install as a dependency. A command-line tool copies each component's source into your project, where it becomes a normal file you can read and change. The components are styled with Tailwind CSS and built on a headless library underneath: Base UI by default since July 2026, with Radix and React Aria as the other two options.
That's the one-paragraph answer. The rest of this guide is for developers deciding whether to use it, and for people who used it a year ago and want to know what's different now. A lot is. There are three foundations instead of one, eight visual styles instead of two, a registry system that half the React ecosystem now publishes through, and a new cn package. Most tutorials that rank for "shadcn" predate several of those changes, so we've included a table of outdated advice near the end.
We checked every fact below against the shadcn/ui docs, its changelog, the GitHub repository and the npm registry on 22 November 2026. We also build on it every day: themes.dev sells blocks and website themes made with shadcn/ui, and we mention them where they're relevant. shadcn/ui itself has nothing to sell, and nothing here is sponsored.
shadcn/ui at a glance#
| November 2026 | |
|---|---|
| What it is | Component source code you copy into a React project with a CLI |
| Made by | shadcn, working at Vercel |
| Licence and price | MIT, free, no paid tier |
| Current CLI | shadcn 4.23.0 (v4 since March 2026) |
| Foundations | Base UI (default), Radix, React Aria |
| Styling | Tailwind CSS v4, CSS variables in OKLCH |
| Official setup guides | Next.js, Vite, TanStack Start, Laravel, React Router, Astro, manual |
| Components | 66 on the official index |
| GitHub stars | About 129,000 |
1. It's code you own, not a package you import#
The docs open with a line that confuses people at first: "This is not a component library. It is how you build your component library." What it means in practice is that nothing called shadcn-ui sits in your node_modules and gets imported at runtime. When you add a button, the CLI writes components/ui/button.tsx into your repository. From then on it's your button.
Here's the top of the file the CLI writes for a Button on the default setup today:
import { Button as ButtonPrimitive } from "@base-ui/react/button"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "cn"
const buttonVariants = cva(
"group/button inline-flex shrink-0 items-center justify-center rounded-lg ...",
{
variants: {
variant: {
default: "bg-primary text-primary-foreground hover:bg-primary/80",
outline: "border-border bg-background hover:bg-muted ...",
ghost: "hover:bg-muted hover:text-foreground ...",
link: "text-primary underline-offset-4 hover:underline",
// ...
},
},
}
)Three dependencies show up: the headless primitive (here @base-ui/react), class-variance-authority for the variants, and cn for merging class names. Everything visual is Tailwind classes in a file you can edit. Want a brand variant, a different focus ring or a bigger default size? You change the file. You don't wrap the component, override its theme object or fight its CSS specificity.
That's the whole appeal, and also most of the cost, which we come back to in updating and where it falls short.
2. It's free and MIT-licensed, and there's no paid tier#
The repository and the shadcn npm package are both MIT. You can use the components in commercial products, client work and products you sell; the licence only asks that its notice stays with the code. There's no "shadcn/ui Pro".
Everything paid that you see around it comes from third parties: Figma kits, block libraries, templates and themes. That includes us. Those products have their own licences, which usually allow use in your projects but not reselling the code as your own kit. Read them separately; the MIT licence of shadcn/ui doesn't carry over to someone else's blocks built on top of it.
3. Who makes it, and how it got here#
shadcn/ui is the work of a developer who goes by shadcn. The site's footer reads "Built by shadcn at Vercel", and the docs have a deploy-on-Vercel box, but the code doesn't depend on Vercel in any way. The repository was created in January 2023. The first changelog entry, "New CLI, Styles and more", is from June 2023.
A short history explains a lot of the advice you'll find online:
- 2023: the original
shadcn-uiCLI, two styles (default and New York), Radix underneath, Tailwind v3. - 2024: the package is renamed to
shadcn, blocks arrive, the CLI is rewritten in August, and React 19 support lands in October. - 2025: Tailwind v4 in February (OKLCH colours, the default style deprecated), the registry schema, MCP and CLI 3.0 in August, a community registry index in September, and the
shadcn createbuilder with five new styles in December. - 2026: CLI v4 in March, GitHub repos as registries in June, Base UI as the default and React Aria as a third foundation in July, private GitHub registries in August, the
cnpackage in September, AI Elements in October.
The repo has about 129,000 stars and 11,400 forks, which makes it one of the most-starred frontend projects on GitHub.
4. What init and add actually do#
Two commands cover most of what you'll do:
npx shadcn@latest init
npx shadcn@latest add button dialoginit asks a few questions (or takes them as flags), then writes:
components.json, the project's settings (next section);- your theme as CSS variables in the global stylesheet, plus an import of
shadcn/tailwind.cssfor shared variants; lib/utils.ts, which since September 2026 is a single line:export { cn } from "cn".
add fetches each component's definition, installs its npm dependencies, adds any other components it depends on, and writes the files where your aliases point. Adding a Dialog, for example, also gives you the Button it uses.
For a new project, init can scaffold the whole app with -t: next, vite, start (TanStack Start), react-router, laravel or astro. Add --monorepo for a workspace layout. npx shadcn@latest init -d skips the questions and gives you Next.js with the Nova style.
The rest of the CLI is worth knowing too:
| Command | What it's for |
|---|---|
view <item> | Print an item's files before installing it |
search (or list) | Search one or more registries |
add --dry-run, --diff, --view | See what an install would change, or what changed upstream |
apply --preset <code> | Switch an existing project to another theme, font or style |
migrate <name> | Codemods: cn, icons, base-color, radix, rtl |
info, docs <component> | Project details and component docs in the terminal, for you or an agent |
build, registry validate | For people publishing their own registry |
eject | Remove the shadcn dependency for good (can't be undone) |
mcp init | Set up the MCP server for an AI client |
The CLI needs Node 20.18.1 or later. pnpm dlx, yarn dlx and bunx --bun work as well as npx. Note that it's npx shadcn, not npx shadcn-ui: the old package stopped at 0.9.5 and still turns up in tutorials.
5. components.json, field by field#
This file is how the CLI knows where things go and how they should look. Some fields are fixed once you've run init, so it's worth understanding before you start.
| Field | What it does | Change later? |
|---|---|---|
style | Foundation plus style, such as base-nova or radix-vega | Not by editing; use apply |
tailwind.css | The stylesheet that imports Tailwind and holds your tokens | Yes |
tailwind.config | Path to a Tailwind config; leave empty on v4 | Yes |
tailwind.baseColor | The neutral palette the theme starts from | With migrate base-color |
tailwind.cssVariables | Tokens as CSS variables (true) or colours written into classes (false) | Only by reinstalling components |
tailwind.prefix | A prefix for utilities, like tw- | Yes, for new installs |
rsc | Adds "use client" to interactive components | Yes |
tsx | Set to false for .jsx files | Yes |
aliases | Where components, ui, lib, hooks and utils live | Yes |
iconLibrary | lucide, tabler, hugeicons, phosphor or remixicon | With migrate icons |
rtl | Converts physical classes to logical ones on install | With migrate rtl |
registries | Third-party registries by @name | Yes |
Two details trip people up. There's no separate base field: the foundation is the first half of style. And aliases can now point at package.json imports (#components/ui) instead of tsconfig paths, which helps in monorepos.
6. There are three foundations now: Base UI, Radix and React Aria#
For its first three years shadcn/ui meant Radix underneath. That's no longer true. The headless layer, the part that handles focus, keyboard behaviour and ARIA, can be one of three libraries, and nearly every component exists for all three.
| Base UI | Radix | React Aria | |
|---|---|---|---|
| Package | @base-ui/react | radix-ui | react-aria-components |
| From | The team behind Radix and MUI | WorkOS | Adobe |
| In shadcn/ui since | December 2025; default since July 2026 | 2023 | July 2026 |
| Pick it with | init (or -b base) | init -b radix | init -b aria |
| Composition API | render prop | asChild | Render props |
| Strongest at | Active development, forms and newer components | Maturity; most existing code and tutorials | Internationalisation, dates, touch and screen-reader detail |
The shadcn team's own advice is short: "Starting something new? We recommend Base UI." If you're already on Radix, the same changelog says "Radix is not being deprecated" and "You do not need to migrate."
Pick React Aria if your app is heavy on dates, numbers and languages, or if you need its very thorough accessibility testing. Pick Radix if you depend on blocks or a codebase written for it. Otherwise the default is a fine choice.
7. Base UI became the default in July 2026, and your code shows it#
If you run init today without flags, you get Base UI. Scripts in CI that expected Radix need -b radix added. The docs also open on the Base UI tab, and component pages now live at three addresses: /docs/components/base/…, /radix/… and /aria/….
The most visible change is how you swap the rendered element. Radix uses asChild:
<DialogTrigger asChild>
<Button variant="outline">Edit profile</Button>
</DialogTrigger>Base UI uses a render prop:
<DialogTrigger render={<Button variant="outline" />}>
Edit profile
</DialogTrigger>Two practical things follow from this. First, check which foundation an example was written for before you paste it; an asChild on a Base UI component won't do what you expect. Second, the docs warn against <Button render={<a />} nativeButton={false} /> for links, because Base UI's Button always sets role="button" and the link stops being announced as a link. For a link that looks like a button, use buttonVariants() on a plain <a>.
There's no CLI command for moving from Radix to Base UI. The changelog points to an agent skill (npx skills add shadcn/ui) that migrates one component per commit and flags behaviour changes in a report instead of patching them.
8. There are eight styles, and they change more than colour#
Older guides talk about "Default" and "New York". Default was deprecated in February 2025, and in December 2025 the two were replaced by named styles. There are eight now:
| Style | Added | What it looks like |
|---|---|---|
| Vega | Dec 2025 | The classic shadcn/ui look |
| Nova | Dec 2025 | Vega with tighter padding and margins |
| Maia | Dec 2025 | Rounded, generous spacing |
| Lyra | Dec 2025 | Boxy and sharp, made for mono fonts |
| Mira | Dec 2025 | Compact, for dense interfaces |
| Luma | Mar 2026 | Rounded with soft elevation |
| Sera | Apr 2026 | Editorial: serif headings, square corners, underlined controls |
| Rhea | May 2026 | A more compact Luma |
A style isn't a colour scheme. It changes the component code itself: padding, radius, borders, sometimes the markup. That's why Rhea is a separate style rather than a spacing variable on Luma; changing --spacing would change what p-2 means everywhere in your app.
Each of the eight works with each of the three foundations, which is where values like base-nova and aria-luma in components.json come from.
9. Theming runs on CSS variables, now in OKLCH#
Colours aren't hard-coded in the components. They read semantic tokens: bg-primary, text-muted-foreground, border-border. You define those tokens once, in your stylesheet, for light and dark.
The naming rule is simple: a surface and the text that sits on it come in pairs. --primary goes with --primary-foreground, --card with --card-foreground. The full set covers background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, five chart colours and eight sidebar tokens, plus --radius (0.625rem by default). The current scaffold has --destructive without a matching foreground, which surprises people copying older themes.
Since the Tailwind v4 update, values are written in OKLCH instead of HSL:
:root {
--background: oklch(1 0 0);
--primary: oklch(0.205 0 0);
--warning: oklch(0.84 0.16 84);
}
.dark {
--warning: oklch(0.41 0.11 46);
}
@theme inline {
--color-warning: var(--warning);
}The last block is how you add a colour of your own: define it for both modes, map it in @theme inline, and bg-warning works like any built-in token.
The base colours you can start from changed too. They're now Neutral, Stone, Zinc, Mauve, Olive, Mist and Taupe; Gray and Slate are gone from new projects. If you need to pick a palette by eye, our Tailwind colour reference lists the v4 values.
10. The themes page became /create, and themes became presets#
ui.shadcn.com/themes now redirects to ui.shadcn.com/create. There you pick a foundation, style, base colour, accent, radius, fonts and icon set, and preview the result on real screens. The output is a preset: a short code that holds all those choices.
# start a project from a preset
npx shadcn@latest init --preset <code>
# switch an existing project
npx shadcn@latest apply --preset <code>
# only take the colours and fonts
npx shadcn@latest apply --preset <code> --only theme,fontapply reinstalls your components in the new style, so commit first; anything you changed by hand in those files will be overwritten. Presets are shareable as a URL, which makes them handy for agreeing on a look with a designer before anyone writes code.
Worth knowing for anyone who buys blocks: a "shadcn theme" from a vendor usually means a set of these tokens, while a website theme like the ones on our shadcn themes page is a whole site. Blocks that only use the semantic tokens follow whichever preset you apply.
11. Dark mode is a class on the root element#
Every token has a value under :root and another under .dark. Put the dark class on <html> and the whole interface switches. Nothing in the components checks the mode themselves.
What you need is something that sets that class, remembers the choice and avoids a flash of the wrong theme on load. The official guides cover Next.js (with the next-themes package), Vite (a small ThemeProvider you copy in), Astro, Remix and TanStack Start. When you scaffold with init -t next or -t vite, dark mode is already wired up.
One thing to plan for: test both modes as you build. Custom colours added only to :root are the most common reason a dark mode looks broken in one corner of an app.
12. Tailwind v4 and React 19 are the baseline#
New projects start on Tailwind CSS v4 and React 19. The move, which began in February 2025, changed more than a version number:
- There's usually no
tailwind.config.js. Configuration lives in CSS with@themeand@theme inline. - Colours moved from HSL to OKLCH.
tailwindcss-animatewas replaced bytw-animate-css, imported in your CSS.forwardRefis gone; components takeReact.ComponentProps, since React 19 passesrefas a normal prop.- Every part carries a
data-slotattribute, so you can style, say, every[data-slot=card-header]from outside. - Buttons use the default cursor instead of a pointer. If you want the pointer back,
init --pointeradds the CSS. w-4 h-4becamesize-4throughout.
Apps on Tailwind v3 and React 18 keep working; the docs say so plainly. The v3-era docs live at v3.shadcn.com, and that's what you should read if you maintain one. If you're on v3 and copying from today's docs, expect the CSS setup and colour values not to match.
13. It runs on most React frameworks, and only React#
The installation page lists seven guides: Next.js, Vite, TanStack Start, Laravel, React Router, Astro and a manual setup for anything else. Remix, Gatsby and TanStack Router used to be on that list. Their pages still load if you know the address, and the Remix one points you to React Router.
All three foundations are React libraries, so shadcn/ui itself is React-only. The ports for other frameworks are separate community projects with their own maintainers and release pace:
- Vue: shadcn-vue
- Svelte: shadcn-svelte
- Solid: SolidUI and shadcn-solid
- Angular: Spartan
- Flutter: shadcn_ui
They follow the same idea (copied source, tokens, a CLI) but they don't follow the official changelog, so things like the three foundations or the new styles may not be there.
14. Astro and Next.js need different kinds of care#
The two frameworks people ask us about most handle shadcn/ui differently, and the difference matters for performance.
In Next.js, the App Router renders on the server by default. With "rsc": true in components.json, the CLI adds "use client" to components that need the browser, such as Dialog or Tabs. A Card or Badge stays a server component. The thing to watch is your own code: once a file has "use client", everything it imports ships to the browser, so keep interactive parts small and pass server-rendered content in as children. We go deeper on our shadcn/ui and Next.js page.
In Astro, a React component renders to static HTML and sends no JavaScript unless you add a client: directive. Buttons, cards and badges are free in that sense. Anything that opens, closes or holds state needs a directive, and because Astro islands don't share React context, a Dialog has to live inside one React component that you hydrate as a whole. Our shadcn/ui with Astro post walks through the setup and those rules, and shadcn/ui in Astro shows how our blocks render with no client JavaScript.
15. There are 66 components, and the list keeps changing#
Most "complete lists" online stop at around 50. The official index had 66 on 22 November 2026. The familiar ones are all there: Accordion, Alert Dialog, Button, Calendar, Card, Combobox, Command, Data Table, Date Picker, Dialog, Drawer, Dropdown Menu, Popover, Select, Sheet, Sidebar, Table, Tabs, Tooltip and the rest.
The newer ones tend to get missed:
- October 2025: Field, Input Group, Button Group, Item, Empty, Spinner and Kbd. Small parts, but they replace a lot of hand-rolled markup in forms and lists.
- June 2026: chat parts (Message, Bubble, Attachment, Marker, Message Scroller).
- July and August 2026: a new Toast and Questionnaire, for multi-step question flows.
- October 2026: Trace and Code Block, plus AI Elements, a set of 21 copy-in patterns for AI interfaces (prompt input, reasoning, tool calls) that is replacing the separate AI SDK Elements project.
Sidebar deserves its own mention. Since October 2024 it has been a family of about 25 parts that handle collapsing, mobile sheets and keyboard shortcuts, and it's the backbone of most shadcn dashboards you'll see. Our shadcn dashboard page shows screens built on it, and the dashboard templates comparison covers free starters that use it.
16. Forms moved to the Field component#
For years the advice was: use the Form component, which wraps React Hook Form with FormField, FormItem and FormMessage. The page for that component now redirects to a forms guide built on Field.
Field is a plain layout and labelling component: label, control, description and error, wired together with the right ids and ARIA attributes. It doesn't care which form library you use. The guide has versions for React Hook Form (with its Controller), TanStack Form and Formisch, and Field works with plain server actions too.
<Field data-invalid={!!errors.email}>
<FieldLabel htmlFor="email">Email</FieldLabel>
<Input id="email" type="email" aria-invalid={!!errors.email} {...register("email")} />
<FieldDescription>We only use it for receipts.</FieldDescription>
<FieldError>{errors.email?.message}</FieldError>
</Field>If you have a codebase full of the old Form component, it still works; it's your code. For new forms, Field is less magic and easier to read. Our free library has a Field component page, and the form blocks in the store use the same pattern.
17. Toast, Sonner and Toast again#
This one confuses everybody, with good reason. In February 2025 the original Toast was deprecated in favour of Sonner, a separate toast library. Then in July 2026 a new Toast arrived, built on Base UI, with actions, status types, promise toasts, stacking and swipe to dismiss. React Aria got one too.
So the answer depends on your foundation:
- Base UI or React Aria: use the new Toast. The old Sonner page for Base UI redirects to it.
- Radix: Toast is still marked deprecated; use Sonner.
If a tutorial tells you to install use-toast and a Toaster from 2023, that's the original Toast, and it's not what either path uses today.
18. Charts are Recharts with your tokens#
The Chart component isn't a charting library. It's a thin layer over Recharts, now on Recharts v3, that adds a config object, a styled tooltip and legend, and colours from your theme. Series colours come from var(--chart-1) to var(--chart-5), so charts change along with everything else when you switch theme or mode.
Because it's Recharts underneath, you write normal Recharts code inside a ChartContainer. That's a strength (lots of chart types, good documentation) and a limit: very large datasets and canvas-level performance aren't what Recharts is for. The charts gallery on ui.shadcn.com has dozens of examples to copy.
19. The official blocks cover apps; marketing pages come from elsewhere#
A block is a larger piece made of several components: a login screen, a sidebar layout, a dashboard. The official blocks page has about 30: one dashboard, five login and five sign-up screens, and sixteen sidebars. Each comes in Radix and Base UI versions, and the CLI picks the one that matches your project. You install them like components:
npx shadcn@latest add dashboard-01What's missing on purpose is anything for marketing sites: hero sections, pricing tables, feature grids, testimonials, footers. That gap is why a whole ecosystem of block libraries exists, free and paid. We wrote an honest comparison of thirteen of them, ours included, in best shadcn/ui block libraries.
Our own catalogue covers those sections and app screens. If you're building a site, start from the category you need: hero sections, pricing, features, footers, or the landing page, section by section. For whole pages there are page templates. The free library has blocks and components you can use without paying, and everything else is in UI Pro. For more free starting points see free shadcn/ui templates.
20. Registries turned shadcn/ui into a distribution system#
This is the biggest change of the last two years, and most guides barely mention it. The same mechanism that copies button.tsx into your project can copy anything from anyone. A registry is a set of JSON files that describe items: their files, npm dependencies, other items they need, CSS variables and even environment variables. The CLI installs from any registry the same way it installs from the official one.
There are a few ways to point the CLI at one:
- By URL:
npx shadcn add https://example.com/r/login-form.json - By namespace in
components.json, after whichnpx shadcn add @acme/login-formworks - From a GitHub repo with a
registry.jsonat the root:npx shadcn add owner/repo/item, pinned with#tagif you like. Since August 2026 this works for private repos throughgh author aGH_TOKEN. - From a local file:
npx shadcn add ./block.json
Private registries authenticate with headers or query parameters, and secrets stay in environment variables. This is how we deliver our own blocks, for example:
{
"registries": {
"@themesdev": {
"url": "https://www.themes.dev/r/ui/{name}.json",
"headers": { "Authorization": "Bearer ${THEMESDEV_TOKEN}" }
}
}
}The official registry directory listed 593 registries on the day we checked, and it's built into the CLI's search. Items come in twelve types, from registry:ui and registry:block to registry:page, registry:theme, registry:font and registry:item, which can carry any file at all, with or without React. Teams use that last one to share config files, lint rules and agent instructions.
A word of caution that follows from all this: installing from a registry writes someone else's code into your repo and can add npm packages. Read it first with shadcn view or add --dry-run, the same way you'd read a package before adding it.
21. It was built to be used by AI tools as well as people#
"AI-Ready" is one of the five principles on the docs' first page, and it shows up in several places:
- There's an MCP server.
npx shadcn@latest mcp init --client claudesets it up for Claude Code;cursor,vscode,codexandopencodeare the other clients the docs cover. Your assistant can then browse, search and install from every registry in yourcomponents.json, private ones included. - There are agent skills:
npx skills add shadcn/uigives coding agents the project context (they runshadcn info --json) and is also how the Radix-to-Base-UI migration runs. - The docs are written with models in mind. Every component page has had a Composition section since April 2026 that spells out which parts go inside which, and there's an llms.txt.
shadcn docs buttonprints the docs in the terminal. - Blocks and public registry items can open straight in Vercel's v0 to be edited by prompt.
The reason models write shadcn/ui code well is simpler than any of these features, though: the code is in your repo, in plain Tailwind, in a shape they've seen many times. An assistant can read and change your button. It can't read a compiled component library in node_modules half as easily.
22. There's no npm update, so updating is on you#
Owning the code means upstream fixes don't reach you automatically. When the shadcn team fixes a focus bug in Dialog, your copy keeps the bug until you do something.
The tools for that something:
npx shadcn add dialog --diffshows what changed upstream against your file.--dry-runand--viewshow what an install would write without writing it.npx shadcn add dialog -ooverwrites your file with the current version, including any edits you made. Commit before you run it.migrateruns codemods for the larger moves (thecnpackage, icon libraries, base colours, Radix imports, right-to-left).
A habit that makes this bearable: keep components/ui as close to upstream as you can, and put your own variations in separate components that use them. When you do change a ui file, leave a comment saying why. Then a --diff a year later tells you something useful instead of showing a wall of red.
The shadcn package also stays in your dependencies after init, for the shared CSS. If you'd rather not have it, shadcn eject inlines that CSS and removes it, permanently.
23. Accessibility: the hard parts are done, the rest is yours#
The foundations do the work most teams get wrong when they build from scratch: focus trapping in dialogs, returning focus when they close, arrow-key navigation in menus and tabs, Escape to dismiss, the right roles and aria-* attributes, and labels tied to their controls. React Aria goes furthest, with localised strings in over 30 languages and consistent press and hover handling on touch screens.
What stays with you, whichever foundation you pick:
- Labels: an icon-only button needs an
aria-label; a dialog needs a title, even a visually hidden one. - Contrast: the default tokens pass, but your brand colour on
--primarymight not. Check every pair, in both modes. - Focus styles: the components ship visible focus rings. Don't remove them in the name of a cleaner look.
- Your own edits: because the source is yours, you can break what the primitive guaranteed. Swapping a
DialogTitlefor a plainh2is an easy way to do it. The Composition sections in the docs show the structure each component expects.
Then test with a keyboard and a screen reader before you ship. That part no library does for you.
24. Where it falls short#
shadcn/ui is very good at what it does, and still the wrong choice for some teams. The honest list:
- Maintenance is yours. On a team of one this is fine. Across twenty apps in a company, twenty diverging copies of Dialog is a real cost, and some teams end up packaging their shadcn components as an internal library, which brings back the dependency they were avoiding.
- Decisions at the start stick. Style, foundation and the CSS-variable setting are hard to change later.
applyhelps, but it overwrites files. - Tutorials go stale fast. Three foundations, eight styles and a CLI that ships a minor version every couple of weeks mean much of what you'll find online is written for a setup you don't have.
- It's React only. The Vue, Svelte, Solid and Angular ports are good, but separate, and they lag.
- The sameness problem. Ship the defaults and your product looks like a thousand others. The styles and presets help, but a distinct look still takes design work.
- Fewer complex components than the big libraries. There's a data table recipe built on TanStack Table, not a data grid with virtualised rows, column pinning and Excel export. MUI X or AG Grid exist for a reason.
- Design files are community-made. The Figma page lists four free and eight paid kits, none official, and they don't always match the newest styles.
25. When another library fits better#
If the trade-offs above rule shadcn/ui out, here's roughly where people go instead:
| If you want… | Look at |
|---|---|
| Updates through npm and a styled kit you don't maintain | Mantine, MUI, Chakra UI |
| Complex data grids and date pickers with support | MUI with MUI X |
| Headless parts with your own styling, no Tailwind | Base UI, Radix Primitives or React Aria directly |
| Tailwind styles without React | daisyUI |
| A theme system with props instead of classes | Radix Themes |
Note that the third row is shadcn/ui's own foundations. Using them directly gives you the behaviour without the styling or the CLI. We compare ten of these in more detail, with licences and paid tiers, in shadcn/ui alternatives.
Outdated advice, and what's true now#
If you're following a tutorial and something doesn't match, it's probably one of these:
| You may read | Now (November 2026) | Changed |
|---|---|---|
npx shadcn-ui@latest init | npx shadcn@latest init | 2024 |
| Styles are Default and New York | Eight named styles; Default is deprecated | Feb and Dec 2025 |
| Colours in HSL | OKLCH | Feb 2025 |
Edit tailwind.config.js | Tokens in CSS with @theme inline | Feb 2025 |
Install tailwindcss-animate | tw-animate-css | Mar 2025 |
Components use forwardRef | Plain function components with data-slot | Feb 2025 |
| Base colours include Slate and Gray | Neutral, Stone, Zinc, Mauve, Olive, Mist, Taupe | 2025–2026 |
| Generate a theme at /themes | /create, with presets | Dec 2025 |
| shadcn/ui is built on Radix | Base UI by default; Radix and React Aria optional | Jul 2026 |
| Toast is deprecated, use Sonner | True on Radix only; a new Toast on Base UI and React Aria | Jul 2026 |
Use the Form component with FormField | Field, with your form library of choice | Oct 2025 |
cn is clsx plus tailwind-merge | The cn package | Sep 2026 |
Run npx shadcn diff | npx shadcn add <item> --diff | Mar 2026 |
| Remix and Gatsby setup guides | No longer on the install index | 2026 |
| Charts on Recharts v2 | Recharts v3 | 2026 |
Frequently asked questions#
Is shadcn/ui a component library?
Not in the usual sense. You don't install it and import from it; a CLI copies each component's source into your project and you maintain it from there. The shadcn docs describe it as a way to build your own component library.
Is shadcn/ui free for commercial use?
Yes. It's MIT-licensed, with no paid tier. You can use it in commercial and client projects. Paid blocks and templates built on it are separate products with their own licences.
Does shadcn/ui use Radix or Base UI?
Either, or React Aria. Since July 2026 new projects get Base UI by default. Pass -b radix or -b aria to init for the others. Radix is still supported and existing projects don't need to migrate.
Can I use shadcn/ui without Tailwind CSS?
Not as it comes. Every component is styled with Tailwind classes and the theme is set up for Tailwind v4. If you don't want Tailwind, use Base UI, Radix or React Aria directly and style them yourself.
Does shadcn/ui work with Tailwind v3?
Existing projects on Tailwind v3 and React 18 keep working. New projects start on v4, and the current docs assume it. The v3-era docs are at v3.shadcn.com.
Does shadcn/ui work with Vue, Svelte or Angular?
The official project is React only. Community ports exist: shadcn-vue, shadcn-svelte, SolidUI and shadcn-solid, and Spartan for Angular. They follow the same approach but are maintained separately.
How do I update shadcn/ui components?
Run npx shadcn@latest add <component> --diff to see what changed upstream, then merge by hand or overwrite with -o. Overwriting discards your edits, so commit first.
Is shadcn/ui good for production?
Yes, and it's widely used in production apps. The accessibility work comes from mature headless libraries. The main thing to plan for is that you own the code, so updates and consistency across apps are your team's job.
What is a shadcn registry?
A set of JSON files that describe installable items: components, blocks, pages, themes or plain files. The shadcn CLI can install from any registry by URL, namespace or GitHub repository, which is how third-party libraries distribute their code.
How we wrote this#
Every version number, date and command in this guide comes from ui.shadcn.com (the docs and each changelog entry), the shadcn-ui/ui repository on GitHub, the npm registry and the Base UI, Radix and React Aria docs, read on 22 November 2026. Where the changelog only gives a month, we give a month. The opinions, such as which foundation to pick and how to keep updates manageable, come from building several hundred blocks and app screens on shadcn/ui for themes.dev.
shadcn/ui changes quickly. We'll update this page when a release changes something it says, and note it below. If you spot something that's out of date, tell us.
Changes: 22 November 2026, first published.
