How to Install Components From Any shadcn Registry

The shadcn CLI no longer installs only the official components. Any team can publish a registry, and the same add command pulls code from all of them into your project as source files you own. This guide covers every way to install from a registry, from a one-line namespace command to private registries that need a token.

How registry installs work

A registry is a set of JSON files. Each file describes one item: its source files, the npm packages it needs, other registry items it depends on, and any CSS variables it adds. When you run shadcn add, the CLI fetches that JSON, installs the dependencies, and writes the files to the paths set in your components.json.

That means three things identify an item:

• A namespace and name, such as @magicui/marquee
• A URL pointing straight at the item JSON
• A GitHub address in the form owner/repo/item

Before installing anything from a third-party registry, run init so the project has a components.json:

npx shadcn@latest init

Install with a namespace

Namespaces are the shortest form. The @ prefix tells the CLI which registry to ask:

npx shadcn@latest add @magicui/marquee

You can mix namespaces in a single command:

npx shadcn@latest add @shadcn/card @magicui/marquee @kibo-ui/gantt

For registries listed in the official directory, you do not have to configure anything first. The CLI checks the directory when you run add or search and writes the registry entry into your components.json for you. The directory includes hundreds of public registries, including Magic UI, Kibo UI and Shadcnblocks.

To see what a registry offers before you install, use search (alias list) and view:

npx shadcn@latest search @magicui -q "marquee"
npx shadcn@latest view @magicui/marquee

Add a registry to components.json

If a registry is not in the directory, add it yourself under registries. Each key is the namespace, and each value is a URL template where {name} is replaced with the item name:

{
  "registries": {
    "@acme": "https://registry.acme.com/r/{name}.json"
  }
}

With that entry, npx shadcn@latest add @acme/header fetches https://registry.acme.com/r/header.json.

An optional {style} placeholder is replaced with the style set in your project, for registries that publish one build per style:

{
  "registries": {
    "@themes": "https://registry.example.com/{style}/{name}.json"
  }
}

Install from a URL

You can skip namespaces entirely and pass the item JSON URL. This is useful for one-off installs, testing a registry you are building, or registries that only publish URLs:

npx shadcn@latest add https://magicui.design/r/marquee

Theme registries often work this way. For example, Shadcn Themes documents installs like npx shadcn@latest add https://shadcnthemes.com/r/claude.json.

Install from a GitHub repository

A public GitHub repo with a valid registry.json at its root works as a registry without being submitted anywhere. The first two path segments are the owner and repo, and the rest is the item name:

npx shadcn@latest add acme/toolkit/project-conventions

Append #ref to pin a branch, tag or commit SHA. Pinning to a full commit SHA is the most reproducible option:

npx shadcn@latest add acme/toolkit/project-conventions#v1.0.0

Only github.com repositories are supported, not GitHub Enterprise hosts.

Check what an install will change

Registry items can overwrite files, add dependencies and edit your CSS. The add command has three flags for reviewing that before anything is written:

npx shadcn@latest add @acme/header --dry-run
npx shadcn@latest add @acme/header --diff
npx shadcn@latest add @acme/header --view

--dry-run lists what would happen, --diff shows changes against your existing files, and --view prints the incoming code. Use them on any registry you have not installed from before.

Private and authenticated registries

For internal design systems or paid component libraries, use the object form of a registry entry. It takes a url, plus optional headers and params. Values in ${VAR_NAME} form are read from environment variables:

{
  "registries": {
    "@private": {
      "url": "https://api.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Then put the secret in .env.local, which should not be committed:

REGISTRY_TOKEN=your_secret_token_here

The same pattern covers API keys ("X-API-Key": "${API_KEY}"), license keys, and tokens passed as query parameters through params. The shadcn docs recommend HTTPS for every authenticated registry, and the CLI reports 401, 403 and 429 responses so you can tell an expired token from a rate limit.

Private GitHub registries

Private GitHub repos use your GitHub credentials instead of headers. Locally, run gh auth login once and the CLI reads the repo through the GitHub CLI. In CI, set GH_TOKEN or GITHUB_TOKEN; a fine-grained token with read-only Contents access to that one repo is enough.

GH_TOKEN=github_pat_xxx npx shadcn@latest add acme/private-toolkit/project-conventions

Install through the shadcn MCP server

The shadcn MCP server lets an AI coding assistant browse, search and install registry items from a prompt. It reads the same registries config in components.json, so private registries work as long as the environment variables are set.

For Claude Code, the CLI can write the config for you:

npx shadcn@latest mcp init --client claude

For Cursor (.cursor/mcp.json) and other clients, the config is the same command:

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

VS Code uses .vscode/mcp.json with a servers key instead of mcpServers. After restarting the client, prompts like "find me a login form in the shadcn registry" or "install @acme/auth-form" turn into CLI calls.

Which method to use

Method	Best for	Config needed
@namespace/item (listed registry)	Public libraries in the directory	None
@namespace/item (unlisted)	Registries you use often	registries entry
Item JSON URL	One-off installs, testing	None
owner/repo/item	Registries hosted on GitHub	None for public repos
Object entry with headers	Private or paid registries	registries entry and env vars
MCP server	Installing from an AI assistant	MCP client config

To find registries worth installing from, browse the component libraries and block libraries on this site; most listings show their install command.

FAQ

Do I need to add every registry to components.json?

No. Registries in the official shadcn directory are added automatically the first time you use their namespace. You only need a manual entry for unlisted or private registries.

Can a registry item depend on items from other registries?

Yes. An item's registryDependencies can reference other namespaces, URLs or GitHub addresses, and the CLI resolves each from its own registry during install.

What happens if an item overwrites a file I changed?

The CLI asks before overwriting unless you pass --overwrite or --yes. Run --diff first to see exactly what would change.

Does this work outside Next.js?

Yes. The CLI supports Vite, React Router, Astro, Laravel, TanStack Start and other setups, and installs files to whatever paths your components.json aliases point to.