"Works with shadcn" is used loosely enough to be useless. A library that happens to be built with Tailwind is not compatible with your setup; a library that reads your CSS variables, ships Radix behaviour and installs through the registry format is. The difference decides whether adding it takes ten minutes or a week.
Here is the actual test, and which sources pass it.
The four-part test
Does it read your tokens? The load-bearing one. shadcn components take their colours from CSS variables: --background, --foreground, --primary, --muted, --border, --ring. A component that hardcodes bg-zinc-900 will look correct in one theme and wrong in yours, and every theme change afterwards will miss it. Open the source and look for the variables before anything else.
Does it install through the registry format? npx shadcn add <url> means the CLI resolves dependencies and writes files where your config says they go. Anything that asks you to copy a snippet from a documentation page is a manual paste that nothing tracks.
Does it build on the same primitives? If it uses Radix or Base UI, its dialogs and dropdowns behave like yours and share the portal and focus behaviour. If it ships its own, you now have two implementations of a focus trap in one bundle.
Does it assume a Tailwind version? Tailwind v4 moved configuration into CSS. A component written for v3, with a tailwind.config.js extension it expects you to merge, needs translating rather than installing.
What passes
The registries in the directory that publish a real index all pass the second test by definition, and most pass the first. The ones worth knowing by category:
Extending the primitives. Origin UI is the clearest case: same tokens, same Radix behaviour, more variants. ReUI is the large general set.
Adding what shadcn does not have. Kokonut UI for AI surfaces and backgrounds, Cult UI for interactions, Aceternity and Magic UI for motion.
The catalogue here. Components on 21st install through the same CLI against our registry, which is the second test, and most read the standard tokens.
What does not pass, and why that is fine
A packaged library - MUI, Mantine, Chakra - fails all four tests, and not by accident. It has its own theme object, its own primitives and its own installation model, because it is solving the governance problem rather than the ownership one. The layers guide covers that trade properly.
The mistake is not choosing one. It is running both in the same screen, which produces two focus treatments, two spacing scales and two ideas of what a Button is.
After you install
Two habits that keep a multi-source setup coherent.
Read the diff. add writes files, and it will overwrite button.tsx if two registries both define one. Review what the command touched before committing, every time.
Normalise the tokens in the first commit. An installed component usually arrives with someone else's radius and spacing. Adapting it to your variables while the file is still fresh takes minutes; doing it after three more components have copied its pattern does not.
Where else to look
The honest list, because the answer is not always us:
| Source | Best for | Trade-off |
|---|---|---|
| shadcn/ui | The tokens and primitives everything else is measured against | Deliberately small |
| The registry directory | Finding sources that install through the same CLI | Only registries that publish an index |
| A packaged library | Consistency enforced by an API | Fails every compatibility test, by design |
| 21st | Components with live previews, installed through the same CLI | Quality varies by author, so preview before you take it |
Taking one
Every component page has a live preview and the code. Installing goes through the shadcn CLI against our registry:
That key comes from your 21st account, and installs require a membership. Set API_KEY_21ST once in your shell and the command works for anything in the catalogue. The 21st MCP covers the same ground without leaving the editor: ask Claude, Cursor or Codex for a component, get the previews inline, and let the agent write the file.
Browse the registry directory →
Frequently asked
- What makes a component library shadcn-compatible?
- Four things: it reads your CSS variables rather than hardcoding colours, it installs through the registry format so the CLI resolves dependencies and file paths, it builds on the same primitives so dialogs and dropdowns share focus and portal behaviour, and it does not assume a Tailwind version whose config model has changed.
- How do you tell if a component reads your theme tokens?
- Open the source and look for the variables. A component using bg-background and text-foreground adapts to any theme; one using bg-zinc-900 will look right in one palette and wrong in yours, and every subsequent theme change will silently miss it.
- Can I use MUI or Chakra alongside shadcn?
- Across surfaces, yes; inside one screen, no. A packaged library fails all four compatibility tests by design, because it solves governance rather than ownership. Running both in the same screen produces two focus treatments, two spacing scales and two ideas of what a button is.
- What should I do right after installing a component from another registry?
- Read the diff, because add writes files and two registries that both define a button will overwrite each other. Then normalise the tokens in the same commit: adapting someone else's radius and spacing takes minutes while the file is fresh and much longer after three more components have copied its pattern.