registry:hook custom React hook structure
A registry:hook item defines a custom React hook with an optional dependencies array. The files array contains the hook implementation with type registry:hook. Hooks can depend on npm packages like react.
blocks/registry
330 notes in this subject, read out of this brain and free to use. This is page 4 of 6.
Target placeholders resolve from components.json
Registry items can use target placeholder aliases @components/, @ui/, @lib/, and @hooks/ which are resolved from the project's components.json configuration. These work across projects using @/ aliases, custom TypeScript aliases, package imports, or workspace package exports. Text after the placeholder is preserved (e.g., @ui/ai/prompt-input.tsx installs to the ui directory at ai/prompt-input.tsx).
registry:font Google Font configuration
A registry:font item installs a Google Font with required font field containing: family (font name and fallback), provider (e.g., "google"), import (font import name), variable (CSS variable like --font-sans), subsets array (e.g., ["latin"]), and optional dependency (npm package like @fontsource-variable/inter), weight array, and selector for targeted application.
registry:font with custom selector applies to specific CSS selectors
When a registry:font item includes a selector field (e.g., "h1, h2, h3, h4, h5, h6"), the font utility class is applied via CSS @apply on those selectors within @layer base, while the CSS variable remains injected on the html element for global availability.
registry:font serif example with Lora
Registry font for serif typeface using Lora: ```json { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "font-lora", "type": "registry:font", "font": { "family": "'Lora Variable', serif", "provider": "google", "import": "Lora", "variable": "--font-serif", "subsets": ["latin"], "dependency": "@fontsource-variable/lora" } } ```
registry:base config properties reference
The config field in registry:base supports: style (string, the style name), iconLibrary (string, e.g. "lucide"), rsc (boolean, default false), tsx (boolean, default true), rtl (boolean, default false), menuColor ("default" | "inverted" | "default-translucent" | "inverted-translucent", default "default"), menuAccent ("subtle" | "bold", default "subtle"), tailwind.baseColor (string, e.g. "neutral", "slate", "zinc"), tailwind.css (string, path to Tailwind CSS file), tailwind.prefix (string, prefix for Tailwind classes), aliases.components/utils/ui/lib/hooks (strings for import aliases), registries (Record<string, string | object> with keys starting with @).
registry:base from scratch with extends none
To create a registry:base that doesn't extend shadcn/ui defaults, use extends: "none". This allows defining a complete custom design system with its own dependencies, CSS variables, and configuration without inheriting shadcn/ui base setup.
Common registry item fields
Registry items support common fields: author (string for attribution), devDependencies (array for dev-only packages), meta (object for arbitrary metadata like category and version), and files (array of file objects with path, content, type, and optional target).
cssVars theme object for custom theme variables
The cssVars.theme object allows adding custom theme variables like font-heading, shadow-card, spacing, and breakpoint sizes. These are applied globally across the design system and can override Tailwind CSS defaults.
CSS custom variables override Tailwind CSS variables example
Registry items can override Tailwind CSS variables in the cssVars.theme object, including spacing (e.g., "0.2rem") and breakpoints (e.g., breakpoint-sm: "640px", breakpoint-md: "768px", breakpoint-lg: "1024px", breakpoint-xl: "1280px", breakpoint-2xl: "1536px").
CSS base layer styles in registry items
Registry items can define base layer styles using @layer base with CSS selectors. Example defining h1 and h2 font sizes: ```json "css": { "@layer base": { "h1": { "font-size": "var(--text-2xl)" }, "h2": { "font-size": "var(--text-xl)" } } } ```
Simple CSS utility in registry items
Registry items can define custom CSS utilities using @utility. Simple example: ```json "css": { "@utility content-auto": { "content-visibility": "auto" } } ```
Complex CSS utility with nested selectors
Registry items can define complex utilities with nested selectors: ```json "css": { "@utility scrollbar-hidden": { "scrollbar-hidden": { "&::-webkit-scrollbar": { "display": "none" } } } } ```
Functional CSS utilities with wildcards
Registry items can define functional utilities using wildcards (e.g., @utility tab-*) that accept variable values: ```json "css": { "@utility tab-*": { "tab-size": "var(--tab-size-*)" } } ```
CSS imports in registry items
Registry items can add CSS imports using @import. Imports are placed at the top of the CSS file. Supports basic imports ("tailwindcss", "./styles/base.css"), url() syntax for external sources and local files, and media queries.
CSS import with url() syntax example
Registry items can import CSS using url() syntax: ```json "css": { "@import url(\"https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap\")": {}, "@import url('./local-styles.css')": {} } ```
CSS import with media queries example
Registry items can import CSS with media query conditions: ```json "css": { "@import \"print-styles.css\" print": {}, "@import url(\"mobile.css\") screen and (max-width: 768px)": {} } ```
Tailwind plugins in registry items
Registry items can add Tailwind plugins using @plugin. Plugins from npm packages must also be listed in dependencies. Multiple plugins are automatically grouped, ordered (after imports, before other CSS content), and deduplicated.
Basic Tailwind plugin usage example
Registry items can add Tailwind plugins: ```json "css": { "@plugin \"@tailwindcss/typography\"": {}, "@plugin \"foo\"": {} } ```
Tailwind plugin with npm dependency example
When using Tailwind plugins from npm like @tailwindcss/typography, include in dependencies and css: ```json { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "typography-component", "type": "registry:item", "dependencies": ["@tailwindcss/typography"], "css": { "@plugin \"@tailwindcss/typography\"": {}, "@layer components": { ".prose": { "max-width": "65ch" } } } } ```
Scoped and file-based Tailwind plugins
Registry items can use scoped plugins like @headlessui/tailwindcss, tailwindcss/plugin, or file-based plugins like ./custom-plugin.js: ```json "css": { "@plugin \"@headlessui/tailwindcss\"": {}, "@plugin \"tailwindcss/plugin\"": {}, "@plugin \"./custom-plugin.js\"": {} } ```
Multiple Tailwind plugins ordering
When registry items include multiple plugins (css/@plugin directives), they are automatically grouped, ordered after imports and before other CSS content, and deduplicated. Plugins from dependencies like @tailwindcss/typography, @tailwindcss/forms, and tw-animate-css will all be ordered together.
CSS imports and plugins combined ordering
When registry items use both @import and @plugin directives, the order is: imports first, then plugins, then other CSS content (@layer, @utility, @keyframes).
Combined imports and plugins example
Registry items can combine imports and plugins with automatic ordering: ```json { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "combined-example", "type": "registry:item", "dependencies": ["@tailwindcss/typography", "tw-animate-css"], "css": { "@import \"tailwindcss\"": {}, "@import url(\"https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap\")": {}, "@plugin \"@tailwindcss/typography\"": {}, "@plugin \"tw-animate-css\"": {}, "@layer base": { "body": { "font-family": "Inter, sans-serif" } }, "@utility content-auto": { "content-visibility": "auto" } } } ```
Custom animations with keyframes in registry items
To use custom animations in registry items, define both @keyframes in css and theme in cssVars. Example wiggle animation: ```json { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "custom-component", "type": "registry:component", "cssVars": { "theme": { "--animate-wiggle": "wiggle 1s ease-in-out infinite" } }, "css": { "@keyframes wiggle": { "0%, 100%": { "transform": "rotate(-3deg)" }, "50%": { "transform": "rotate(3deg)" } } } } ```
Environment variables in registry items
Registry items can add environment variables using the envVars field (object with key-value pairs). Variables are added to .env.local or .env file and existing variables are not overwritten. Use envVars only for development or example variables, not production secrets.
Environment variables example
Registry items can define environment variables: ```json { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "custom-item", "type": "registry:item", "envVars": { "NEXT_PUBLIC_APP_URL": "http://localhost:4000", "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/postgres", "OPENAI_API_KEY": "" } } ```
Universal registry items framework agnostic
As of version 2.9.0, registry items can be universal (framework agnostic) by making all files have explicit targets. This allows items to be installed without framework detection or components.json. Universal items use registry:file type for non-framework-specific files.
Universal registry item for Cursor rules example
Universal registry items can install custom configuration files. Example for Python Cursor rules: ```json { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "python-rules", "type": "registry:item", "files": [ { "path": "/path/to/your/registry/default/custom-python.mdc", "type": "registry:file", "target": "~/.cursor/rules/custom-python.mdc", "content": "..." } ] } ```
Universal registry item for ESLint config example
Universal registry items can install ESLint configuration: ```json { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "my-eslint-config", "type": "registry:item", "files": [ { "path": "/path/to/your/registry/default/custom-eslint.json", "type": "registry:file", "target": "~/.eslintrc.json", "content": "..." } ] } ```
Universal registry item with multiple files
Universal registry items can install multiple files with explicit targets: ```json { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "my-custom-starter-template", "type": "registry:item", "dependencies": ["better-auth"], "files": [ { "path": "/path/to/file-01.json", "type": "registry:file", "target": "~/file-01.json", "content": "..." }, { "path": "/path/to/file-02.vue", "type": "registry:file", "target": "~/pages/file-02.vue", "content": "..." } ] } ```
Registry item types available
The shadcn/ui registry supports the following item types: registry:style (extends or creates custom styles), registry:theme (custom theme definitions), registry:block (blocks that install multiple components), registry:ui (reusable UI components), registry:lib (utility libraries), registry:hook (custom React hooks), registry:font (Google Fonts with configuration), registry:base (complete design system bases), and registry:file (universal files not tied to a framework). Each type serves a different purpose in the registry ecosystem.
registry:style extends shadcn/ui by default
A registry:style item extends the default shadcn/ui setup unless explicitly set with extends: "none". When installed via npx shadcn init or npx shadcn add, it can install npm dependencies, add registry dependencies (including remote URLs), and set CSS variables for theme, light, and dark modes.
registry:style custom style from scratch example
To create a custom style from scratch without extending shadcn/ui, set extends: "none" in the registry item. This example installs tailwind-merge and clsx as dependencies, adds utils, button, input, label, and select from registries, and defines custom CSS variables main, bg, border, text, and ring for both light and dark modes: ```json { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "extends": "none", "name": "new-style", "type": "registry:style", "dependencies": ["tailwind-merge", "clsx"], "registryDependencies": [ "utils", "https://example.com/r/button.json", "https://example.com/r/input.json", "https://example.com/r/label.json", "https://example.com/r/select.json" ], "cssVars": { "theme": { "font-sans": "Inter, sans-serif" }, "light": { "main": "#88aaee", "bg": "#dfe5f2", "border": "#000", "text": "#000", "ring": "#000" }, "dark": { "main": "#88aaee", "bg": "#272933", "border": "#000", "text": "#e6e6e6", "ring": "#fff" } } } ```
Registry documentation structure
The registry documentation includes sections for: Getting Started (set up and build your own registry), GitHub (turn a GitHub repository into a registry), Namespaces (configure registries with namespaces), Authentication (secure your registry with authentication), Examples (browse example registry items), and Schema (schema specification for registry.json).
Registry purpose and distribution
The shadcn CLI can be used to run your own code registry. Running your own registry allows you to distribute custom components, hooks, pages, config, rules and other files to any project.
Registry framework compatibility
The registry works with any project type and any framework, and is not limited to React.
GitHub item address format explanation
In a GitHub item address like owner/repo/item, 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.
Review before installing from GitHub registry
Treat GitHub item addresses like third-party code dependencies. Before installing: review the repository and root registry.json, review the item definition especially files, target, dependencies, devDependencies, registryDependencies and envVars, check external registry dependencies, prefer pinned refs using full 40-character commit SHAs, use shadcn view to inspect resolved item payload, pipe shadcn view output to an agent for help checking, use shadcn add --dry-run to preview install without writing files, use --diff or --view flags to inspect changes before applying.
GitHub registry dependencies same repository
Use registryDependencies array in an item to declare dependencies on other registry items. For dependencies in the same GitHub repository, use the full GitHub item address: "registryDependencies": ["owner/repo/item-name"]. Multiple dependencies can be listed in the array. An item can depend on another item from the same repository.
GitHub registry organize with include
For larger repositories, keep item definitions close to source files using nested registry.json files. The root registry.json can include nested files using an include array: "include": ["config/registry.json", "rules/registry.json"]. When using include, file paths in included registry files are relative to that registry.json file's location, not the root.
GitHub registry list and search commands
List every item in a GitHub registry: npx shadcn@latest list <owner>/<repo>. Search a registry: npx shadcn@latest search <owner>/<repo> --query <term> or npx shadcn@latest search <owner>/<repo> -q <term>. View one item's payload: npx shadcn@latest view <owner>/<repo>/<item>
GitHub registry validation command
Validate a GitHub registry using: npx shadcn@latest registry validate <owner>/<repo>. The command reads the root registry.json, resolves includes, validates registry items, and checks that referenced files exist. You can validate a specific branch, tag or commit SHA by appending a hash: npx shadcn@latest registry validate <owner>/<repo>#<ref>
GitHub registry overview
Any public GitHub repository can be turned into a registry by adding a registry.json file to the root. Users can install items using the command: npx shadcn@latest add <username>/<repo>/<item>. The GitHub repository becomes the source registry without needing a registry server or publishing generated JSON files.
GitHub registry item types supported
Registry items are not limited to React components or code. They can include any files from the repository: source files, configuration, docs, templates, workflows, rules, project conventions, helpers and utilities, design system packages, feature kits, agent workflows, codemods and migration kits, testing setup, CI and release workflows, project automation, issue and pull request templates, and MCP configuration.
GitHub registry requirements
A GitHub registry must be a public 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. Private repositories and GitHub Enterprise hosts are not currently supported. For private or authenticated registries, use a namespace with authentication.
GitHub registry dependency refs pinning
Refs are not inherited across dependencies. If a dependency should be pinned to a specific version, include its own ref: "registryDependencies": ["owner/repo/item#v1.0.0", "owner/repo/item#c0ffee254729296a45d6691db565cf707a3fef5d"]. Use tags like v1.0.0 or full 40-character commit SHAs for reproducibility.
Create GitHub registry.json structure
Add registry.json at the repository root. The file must include a $schema field pointing to https://ui.shadcn.com/schema/registry.json, a name field, a homepage field with the GitHub repository URL, and an items array. Each item has name, type (registry:item), title, description, and a files array. Each file object contains path (source in repo), type (registry:file), and target (where to write in user's project, using ~ for home directory).
GitHub registry dependencies external
Items can depend on external registries outside their own repository. Use the full item address for external dependencies: "registryDependencies": ["@namespace/item-name", "owner/repo/item-name"]. External dependencies are resolved from their own registries.
GitHub registry install with refs
Use #ref syntax to install from a specific branch, tag or commit SHA: npx shadcn@latest add owner/repo/item#main, npx shadcn@latest add owner/repo/item#v1.0.0, npx shadcn@latest add owner/repo/item#c0ffee254729296a45d6691db565cf707a3fef5d. Refs may contain slashes like feature/conventions. If no ref is provided, the CLI uses the repository default branch.
GitHub registry CLI commands summary
List items: npx shadcn@latest list owner/repo. Search items: npx shadcn@latest search owner/repo -q query. Validate registry: npx shadcn@latest registry validate owner/repo. Install item: npx shadcn@latest add owner/repo/item. View item payload: npx shadcn@latest view owner/repo/item. For registry item names containing slashes: npx shadcn@latest add owner/repo/rules/agent.
Configure custom registry in components.json for MCP
To use a custom registry with MCP, add a 'registries' object to your components.json file with a key like '@acme' mapped to the registry URL pattern. Example: {"registries": {"@acme": "https://acme.com/r/{name}.json"}}
MCP registry best practices for naming consistency
Use kebab-case for component names and maintain naming consistency across your registry.
MCP server works with any shadcn-compatible registry out of the box
The shadcn MCP server is compatible with any shadcn-compatible registry and requires no special configuration to enable MCP support for your registry.
MCP registry requires registry.json file at root
The MCP server requests your registry index. You must have a registry item file at the root of your registry named either 'registry' or 'registry.json'. For example, if your registry is hosted at https://acme.com/r/[name].json, you should have a file at https://acme.com/r/registry.json or https://acme.com/r/registry. This file must be valid JSON conforming to the registry schema.
MCP registry best practices for registry dependencies
Use 'registryDependencies' in your registry items to indicate relationships between items.
Claude Code MCP setup
For Claude Code: 1) Configure your registry in components.json with the registries object. 2) Run 'npx shadcn@latest mcp init --client claude'. 3) Restart Claude Code. 4) You can use the '/mcp' command to debug the MCP server. Example prompts: 'Show me the components in the acme registry' or 'Create a landing page using items from the acme registry'.
Cursor MCP setup
For Cursor: 1) Configure your registry in components.json with the registries object. 2) Run 'npx shadcn@latest mcp init --client cursor'. 3) Open Cursor Settings and enable the MCP server for shadcn. 4) Try example prompts like 'Show me the components in the acme registry' or 'Create a landing page using items from the acme registry'.
VS Code MCP setup
For VS Code: 1) Configure your registry in components.json with the registries object. 2) Run 'npx shadcn@latest mcp init --client vscode'. 3) Open .vscode/mcp.json and click Start next to the shadcn server. 4) Use GitHub Copilot with prompts like 'Show me the components in the acme registry' or 'Create a landing page using items from the acme registry'.
Codex MCP setup
For Codex: 1) Configure your registry in components.json with the registries object. 2) Add the following to ~/.codex/config.toml: [mcp_servers.shadcn] with command = 'npx' and args = ['shadcn@latest', 'mcp']. 3) Restart Codex. 4) Try prompts like 'Show me the components in the acme registry' or 'Create a landing page using items from the acme registry'.