Registry index location
The full list of open source registries is available at https://ui.shadcn.com/r/registries.json
registry & publishing
44 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Public GitHub registries do not need directory submission
You do not need to submit a public GitHub registry to the registry directory to use it with `owner/repo/item` addresses. The registry directory is for namespaces such as `@acme`.
Steps to add a registry to the directory
To add a registry: (1) Add your registry to `apps/v4/registry/directory.json` in the shadcn-ui repository. (2) Run `pnpm validate:registries` to validate the registry directory. (3) Create a pull request to https://github.com/shadcn-ui/ui. Once the pull request is merged, your registry is published immediately.
Registry requirements
Registry requirements: (1) The registry must be open source and publicly accessible. (2) The registry must be a valid JSON file that conforms to the registry schema specification. (3) The registry is expected to be a flat registry with no nested items; `/registry.json` and `/component-name.json` files are expected to be in the root of the registry. (4) The `files` array, if present, must NOT include a `content` property.
Valid registry JSON structure example
A valid registry has the following structure: The root must contain `$schema` (URL to schema), `name` (string for namespace), `homepage` (URL), and `items` (array of registry items). Each item must have `name` (string), `type` (e.g., "registry:component"), `title` (string), `description` (string), and `files` (array). Each file object must have `path` (string to file) and `type` (e.g., "registry:component"). The `files` array must not include a `content` property.
Registry Health monitoring after publication
Registry Health starts monitoring a registry after publication and does not delay or gate publication while it collects baseline data.
registry:style type definition and fields
A registry:style item defines a custom style that can extend shadcn/ui or be created from scratch. It supports fields: $schema, name, type ("registry:style"), extends (optional, omit to extend shadcn/ui defaults or set to "none" for custom from scratch), dependencies (npm packages), registryDependencies (registry item names or URLs), and cssVars (theme, light, dark color definitions).
registry:theme type definition
A registry:theme item defines a custom theme. It uses cssVars with light and dark sections containing color variable definitions in oklch() or other color formats. Example variables include background, foreground, primary, primary-foreground, ring, sidebar-primary, sidebar-primary-foreground, sidebar-ring.
registry:block type definition
A registry:block item represents a complete block or template. It has fields: $schema, name, type ("registry:block"), description, registryDependencies, and files array. Each file has path, content, type (registry:page, registry:component, etc.), and optional target. Blocks can install other registry items as dependencies.
registry:ui type definition
A registry:ui item represents a reusable UI component. It has fields: $schema, name, type ("registry:ui"), dependencies (npm packages), registryDependencies (other registry items), cssVars (optional color variables), and files array containing the component code.
registry:lib type definition
A registry:lib item represents utility libraries or helper code. It has fields: $schema, name, type ("registry:lib"), dependencies, and files array. Used for sharing helper functions, constants, and non-component code.
registry:hook type definition
A registry:hook item represents a custom React hook. It has fields: $schema, name, type ("registry:hook"), optional dependencies, and files array containing the hook code.
registry:font type definition and font field structure
A registry:font item installs a Google Font. It requires a font field with properties: family (CSS font-family string), provider (e.g. "google"), import (font name), variable (CSS variable name like --font-sans), subsets (array of font subsets like ["latin"]), optional weight (array of font weights), optional selector (CSS selector for targeted application instead of html element), and dependency (npm package name).
registry:base type definition and config field
A registry:base item defines a complete design system base. The config field (optional) accepts: style (string), iconLibrary (string like "lucide"), rsc (boolean, defaults false), tsx (boolean, defaults true), rtl (boolean, defaults false), menuColor ("default" | "inverted" | "default-translucent" | "inverted-translucent", defaults "default"), menuAccent ("subtle" | "bold", defaults "subtle"), tailwind.baseColor (string like "neutral", "slate", "zinc"), tailwind.css (path to Tailwind CSS file), tailwind.prefix (prefix for Tailwind classes), aliases.components, aliases.utils, aliases.ui, aliases.lib, aliases.hooks (all strings for import aliases), and registries (Record<string, string | object> with keys starting with @).
Common registry item fields
Registry items can include: author (string), devDependencies (array of dev dependency package names), meta (object for arbitrary metadata like category and version).
Target placeholders in registry items
Registry items support target placeholders @components/, @ui/, @lib/, @hooks/ that are resolved from components.json to the user's configured directories. The same registry item works across projects using @/, custom TypeScript aliases, package imports, or workspace exports. Text after the placeholder is preserved, e.g. @ui/ai/prompt-input.tsx installs at ui/ai/prompt-input.tsx.
CSS variables in registry items
Registry items support cssVars with theme, light, and dark sections. The theme section defines variables like font-heading, shadow-card, and Tailwind overrides like spacing and breakpoints. Light and dark sections define color-specific variables. Variables can use oklch() color format or other CSS color formats.
Custom CSS in registry items with @layer
Registry items use css field with @layer directives. @layer base applies base styles to HTML elements. @layer components applies component class styles. Styles are defined as CSS objects within the layer.
Custom utilities in registry items
Registry items can define custom utilities using @utility directive. Simple utilities are key-value pairs, e.g. @utility content-auto with { "content-visibility": "auto" }. Complex utilities use nested syntax with selectors like &::-webkit-scrollbar. Functional utilities use wildcard patterns like @utility tab-* with var(--tab-size-*).
CSS imports in registry items
Registry items use @import directive to add CSS imports. Basic syntax: { "@import \"tailwindcss\"": {} }. URL syntax: { "@import url(\"https://fonts.googleapis.com/...\")": {} }. Media query syntax: { "@import \"print-styles.css\" print": {} } or { "@import url(...) screen and (max-width: 768px)": {} }.
Tailwind plugins in registry items
Registry items use @plugin directive to add Tailwind plugins. Syntax: { "@plugin \"@tailwindcss/typography\"": {} }. Plugin packages from npm must also be added to dependencies array. Multiple plugins are automatically deduplicated. Plugins can be scoped packages, file paths like ./custom-plugin.js, or npm packages.
CSS ordering in registry items
When a registry item contains both @import and @plugin directives, imports are placed first, followed by plugins, then other CSS content like @layer, @utility, and @keyframes.
Custom animations in registry items
To use animations in registry items, define @keyframes in the css field and corresponding theme variables in cssVars. Example: cssVars theme defines --animate-wiggle as "wiggle 1s ease-in-out infinite", and css defines @keyframes wiggle with transform rotations.
Environment variables in registry items
Registry items use envVars field (object) to add environment variables. Variables are added to .env.local or .env file. Existing variables are not overwritten. Important: use envVars only for development or example variables, not production variables.
Universal registry items
As of version 2.9.0, universal items are framework-agnostic and can be installed without framework detection or components.json. All files in universal items must have explicit target fields. Examples: .cursor/rules items with target ~/.cursor/rules/custom-python.mdc, ESLint configs with target ~/.eslintrc.json, or multi-file starters with targets like ~/file-01.json and ~/pages/file-02.vue.
Font selector in registry:font items
The selector field in registry:font items applies a font to specific CSS selectors instead of globally on html. When selector is set, the font utility class (e.g. font-heading) is applied via CSS @apply on the specified selector within @layer base. The CSS variable is still injected on html so it is available globally.
registry:base extends field
A registry:base item can set extends to "none" to create a base that doesn't extend shadcn/ui defaults. This creates a complete custom design system from scratch.
registry:style on init behavior
When a custom registry:style that extends shadcn/ui is applied on npx shadcn init, it installs declared npm dependencies, adds registryDependencies items to the project, and applies cssVars (font variables to theme, colors to light and dark modes).
File fields in registry items
Files in registry items have fields: path (source path in registry), content (file content string), type (registry:page, registry:component, registry:ui, registry:lib, registry:hook, registry:file), and optional target (destination path using placeholders or absolute paths).
GitHub repository registry installation syntax
Users can install registry items from GitHub repositories using the command `npx shadcn@latest add <username>/<repo>/<item>`. This allows installing directly from any GitHub repository that contains a registry.json file at its root.
GitHub registry requirements
A GitHub registry must be a github.com repository with a registry.json file at the repository root. It must use valid registry.json and registry-item.json schemas, and reference source files that exist in the repository. Public repositories work with zero configuration. Private repositories work with GitHub credentials. GitHub Enterprise hosts are not supported by GitHub addresses.
registry.json structure for GitHub registries
A registry.json file at the repository root contains a $schema field pointing to https://ui.shadcn.com/schema/registry.json, a name field for the registry, a homepage field with the repository URL, and an items array defining each registry item. Each item has a name, type (registry:item), title, description, and files array. Each file has a path (relative to repository root), type (registry:file), and target (destination in user's project).
Registry items are not limited to React components
Registry items can include any files from a repository: source files, configuration, docs, templates, workflows, rules, or project conventions. Examples include components, helpers and utilities, design system packages, feature kits, agent workflows, project conventions, codemods and migration kits, testing setup, CI and release workflows, project automation, issue and pull request templates, and MCP configuration.
GitHub registry include feature
For larger repositories, use the include field in root registry.json to keep item definitions close to source files. The root registry.json can include nested registry files with: `"include": ["config/registry.json", "rules/registry.json"]`. When using include, file paths in included registry files are relative to that registry.json file, not the root.
Registry dependencies - same repository
Use the registryDependencies field when one registry item depends on another. For dependencies in the same GitHub repository, use the full GitHub item address format: `"acme/toolkit/agent-rules"`. Multiple dependencies can be listed in an array.
Registry dependencies - external registries
Registry items can depend on external registries. Use the full item address for the registry that owns the dependency. Example: `"@acme/tsconfig"` or `"contoso/devtools/prettier-config"`. These are specified in the registryDependencies array alongside same-repository dependencies.
Registry dependency refs and pinning
Refs (branch, tag, or commit SHA) are not inherited across dependencies. If a dependency should be pinned, include its own ref appended with #: `"acme/toolkit/agent-rules#v1.0.0"` or `"acme/toolkit/tsconfig#c0ffee254729296a45d6691db565cf707a3fef5d"`.
GitHub registry refs for branches, tags, and commits
Use # to append a ref when installing from a GitHub registry: `npx shadcn@latest add <username>/<repo>/<item>#<ref>`. Refs can be a branch name, tag, or full 40-character commit SHA. Refs may contain slashes like `feature/conventions`. If no ref is provided, the CLI uses the repository default branch. The CLI uses Git to resolve branches and tags to commit SHAs.
Private GitHub repositories as registries
Private github.com repositories work as registries without configuration. No server setup is required. If you can read the repository, the CLI can install from it. Public repositories are always read anonymously. The CLI tries anonymous access first and only uses credentials when the root registry.json is not publicly readable.
Authenticate private GitHub registry with gh CLI
For local development with private repositories, authenticate once with `gh auth login`. Then install from private repositories like any other GitHub registry: `npx shadcn@latest add acme/private-toolkit/project-conventions`. When a repository is not publicly readable, the CLI reads it through gh using stored credentials. The token stays inside the GitHub CLI and never enters the shadcn process. On first use, the CLI prints a notice: `✔ Using gh credentials.`
Authenticate private GitHub registry with token in CI
Where the GitHub CLI is not installed, set GH_TOKEN or GITHUB_TOKEN environment variable: `GH_TOKEN=github_pat_xxx npx shadcn@latest add acme/private-toolkit/project-conventions`. GH_TOKEN takes precedence over GITHUB_TOKEN. Use a fine-grained personal access token scoped to the repository with Contents: Read-only access (recommended). When a token is set, it is used instead of the GitHub CLI and is only sent to api.github.com.
GitHub registry file size and symlink limits
Registry source files are limited to 5 MiB per file. GitHub Enterprise hosts are not supported—GitHub addresses always resolve against github.com. Avoid symlinks in registry source files. Anonymous reads return the symlink target path as text, while authenticated reads through the Contents API return the target file's content.
GitHub registry item address parsing
For GitHub item addresses, the first two path segments are the GitHub owner and repository. Any remaining segments are the registry item name, not a file path. An address ending in .json is treated as a file path. Example: `acme/toolkit/rules/agent` has owner=acme, repo=toolkit, and item name=rules/agent.
Security review for GitHub registry items
Before installing from a GitHub registry source you do not control, review: the repository and root registry.json, the item definition especially files, target, dependencies, devDependencies, registryDependencies and envVars, and any external registry dependencies which can install files from other registries. Prefer pinned refs for published install commands—a full 40-character commit SHA is most reproducible. Use shadcn view to inspect resolved payload and --dry-run to preview without writing files.