What Is a shadcn Registry and How Do You Add Components From One?

A shadcn registry is a JSON endpoint that the shadcn CLI can read, not a package you install from npm. You add components from one by running npx shadcn@latest add <registry-url>, and the CLI writes the component files directly into your project so you own and edit them. This fits projects already using the shadcn CLI, React, TypeScript, and Tailwind CSS. If you want a versioned dependency you import and never touch, a registry is the wrong tool.

Registry vs. npm package

The distinction matters because it changes what you do after install.

With a registry, the CLI reads the manifest, resolves the listed dependencies, and writes the component source into your project. From that point the file is yours — restyling it, renaming props, or deleting parts won't be overwritten by a future install unless you re-add the same item.

The install command pattern

The shape is always the same:

npx shadcn@latest add <registry-url>

The URL points at a JSON file the CLI understands. A concrete example from UI Beats:

npx shadcn@latest add https://uibeats.com/r/border-beam.json

What happens when you run it:

1. Input — the CLI fetches the JSON at that URL.
2. Action — it reads the file list and dependency list, installs any missing packages, and writes the component files into your configured paths.
3. Expected result — new files appear in your components directory, and the terminal reports which files and dependencies were added.

If your project already has a components.json from a prior shadcn setup, the CLI uses those path aliases. Without it, run npx shadcn@latest init first so the CLI knows where to put things.

Single components vs. whole blocks

A registry can ship one component or a composed section, and the difference shows up in what gets written.

• Single component — one item, one file (plus its dependencies). UI Beats lists 55 of these, including Border Beam, Split Flap, Terminal, Comparison Slider, Rainbow Button, Meteors, Card Stack, Liquid Tabs, and Number Ticker.
• Block — a full section that pulls in every component it's built from. UI Beats ships 3 blocks. Installing the Hero block brings avatar-stack, meteors, and shimmer-button along with it. Installing Feature Grid gives you a finished section rather than a pile of parts.

The practical consequence: a block install is one command that produces several files. Check the terminal output so you know what landed, because you'll be editing more than one file afterward.

Verifying the install

After the command finishes:

1. Open the file the CLI reported and confirm the component renders in your app.
2. Check package.json for any new dependencies the manifest required — motion libraries and icon sets are common additions.
3. Confirm imports resolve against your path aliases. A component that installs but won't import usually means components.json paths don't match your tsconfig.

When a registry URL fails

The CLI can only work with a URL that returns valid registry JSON. Common failure points:

• Wrong path — the endpoint must serve the JSON manifest, not a docs page or a GitHub HTML view. Compare against a known-good URL like https://uibeats.com/r/border-beam.json.
• Network or CORS issues — if the fetch never completes, the CLI reports a fetch error rather than a parse error. Test the URL in a browser first; you should see JSON, not a rendered page.
• Missing init — no components.json means the CLI has nowhere to write. Run init and retry.
• Dependency conflicts — if a required package clashes with your existing versions, the install can fail partway. Read the error, resolve the version, and re-run.

Choosing whether to use one

Use a registry when you want the source in your repo and expect to customize it — animated components, marketing sections, and anything you'll restyle per project fit this. Skip it when you want a stable, versioned dependency you never edit, or when your project isn't on the shadcn CLI, React, TypeScript, and Tailwind stack.