shadcn Registries: How They Work, and Which to Use
A shadcn registry is a set of JSON files that describe components, so the shadcn CLI can install them into your project. You install from a registry either by URL (npx shadcn@latest add https://.../hero.json) or by namespace (npx shadcn@latest add @watermelon/hero-3) after adding the registry to components.json.
How a registry is structured
- A
registry.jsonfile lists every item. Schema:https://ui.shadcn.com/schema/registry.json. - Each item has its own
<name>.jsonfile with its source files and dependencies. Schema:https://ui.shadcn.com/schema/registry-item.json. - Registry authors generate these with
npx shadcn@latest build.
Install by URL
Any registry item URL works with add. For example: npx shadcn@latest add https://registry.watermelon.sh/r/hero-3.json. This needs no configuration, which makes it the easiest way to try a component.
Install by namespace
Add the registry to the registries field in components.json, using {name} as the placeholder for the item name:
"registries": { "@watermelon": "https://registry.watermelon.sh/r/{name}.json" }
Then install with npx shadcn@latest add @watermelon/hero-3, or search with npx shadcn@latest search @watermelon --query hero. Private registries can add auth headers in the same config, with tokens read from environment variables.
The shadcn registry directory
shadcn keeps an official registry directory at ui.shadcn.com/docs/directory. When you use an @namespace that is not in your components.json, the CLI looks it up in that directory and configures it for you. Registries get listed by opening a pull request to the shadcn/ui repository.
Popular registries
Compare options in best free shadcn alternatives.
| Registry | Namespace | Best for |
|---|---|---|
| Watermelon UI | @watermelon (add to components.json) | Free blocks, dashboards, and 130+ animated components |
| Magic UI | @magicui | Animated landing page components |
| Aceternity UI | @aceternity | Animated visual effects |
| Kibo UI | @kibo-ui | Advanced app components |
| Supabase UI | @supabase | Auth, storage, and realtime components for Supabase |
| AI Elements | @ai-elements | Chat and AI interface components |
Frequently asked questions
What is the Watermelon UI registry URL?
Items live at https://registry.watermelon.sh/r/<name>.json, and the full catalog is at https://registry.watermelon.sh/r/registry.json.
Can my AI agent use a registry?
Yes. The shadcn MCP server reads the registries in your components.json. See the shadcn MCP server guide.