blocks/registry

330 notes in this subject, read out of this brain and free to use. This is page 6 of 6.

registry.json include path resolution

When shadcn build resolves includes, item file paths in included registry.json files are read relative to the directory containing that registry.json file. The generated registry output is flattened and does not contain include entries. Registry item names must be unique across the resolved registry, including all included files.

registry.json items structure example

Each item in the items array must have: name (string, required, unique across the registry), type (string, e.g., 'registry:block' or 'registry:ui'), title (string), description (string), registryDependencies (array of strings, can reference components by name, scoped packages like '@acme/input-form', or full URLs like 'https://example.com/r/foo'), dependencies (array of strings with version specifiers like 'is-even@3.0.0'), and files (array of file objects with path and type properties). See registry-item schema documentation for complete specification.

registry.json file object properties

Each file object in the files array must have: path (string, the file path relative to the registry.json location) and type (string, e.g., 'registry:component' or 'registry:ui').

registry.json multiple files example

A registry item can include multiple files in its files array. Each file is defined with its own path (relative to the registry.json file) and type properties.

GitHub repositories as registries

Public GitHub repositories can use the same source registry format as local registries. The CLI reads the root registry.json, resolves include references, and installs files from the repository. See the GitHub registry documentation for more information.

registry.json top-level properties

The registry.json file has the following top-level properties: $schema (string, the schema URL), name (string, required on root registry, used for data attributes and metadata), homepage (string, URL of the registry homepage, used for data attributes and metadata), include (array of strings, relative paths to other registry.json files), and items (array of registry items, must be defined if include is omitted). The root registry.json must define at least one of items or include.

registry-item.json name property

The name property identifies the item in the registry and must be unique within the registry. It is a required string property.

registry-item.json title property

The title property provides a human-readable title for the registry item. It should be kept short and descriptive.

registry-item.json description property

The description property describes the registry item. It can be longer and more detailed than the title.

registry-item.json type property values

The type property specifies the item type and determines its target path when resolved. Supported types are: registry:base (entire design systems), registry:block (complex components with multiple files), registry:component (simple components), registry:font (fonts), registry:lib (lib and utils), registry:hook (hooks), registry:ui (UI components and single-file primitives), registry:page (page or file-based routes), registry:file (miscellaneous files), registry:style (registry styles like new-york), registry:theme (themes), registry:item (universal registry items).

registry-item.json author property

The author property specifies the author of the registry item. The format is 'Name <email@example.com>'. It can be unique to the registry item or the same as the registry author.

registry-item.json dependencies property

The dependencies property lists npm packages required by the registry item. Use @version notation to specify package versions, for example 'name@1.0.2'. These are production dependencies.

registry-item.json devDependencies property

The devDependencies property lists npm packages needed only during development. Use @version notation to specify versions, for example 'name@1.2.0'.

registry-item.json css property

The css property adds new CSS rules to the project's CSS file. It supports @layer base, @layer components, @utility, @keyframes, @plugin directives and their corresponding CSS rule objects.

registry-item.json registryDependencies property formats

The registryDependencies property lists registry items this item depends on. Formats include: bare names for shadcn/ui items (e.g. 'button', 'input'), namespaced items (e.g. '@acme/input-form'), GitHub registry items with optional tag or commit SHA (e.g. 'acme/ui/button#v1.2.0'), custom registry URLs (e.g. 'https://example.com/r/hello-world.json'), and local file paths (e.g. './hello-world.json'). Bare names refer to built-in shadcn items, not same-repository items; use full GitHub address for same-repository dependencies. References are not inherited across dependencies; pin GitHub dependencies to their own tag or commit SHA for reproducibility.

registry-item.json files property structure

The files property is an array of file objects. Each file object has a path property (string, required), a type property (required, same types as the main type property), and an optional target property. The target property is required for registry:page and registry:file types.

registry-item.json file path property

The path property in file objects specifies the path to the file within the registry. This path is used by the build script to parse, transform, and build the registry JSON payload.

registry-item.json file target property

The target property in file objects indicates where a file should be placed in a project. Use ~ to refer to the project root (e.g. '~/foo.config.js'). The target property is required for registry:page and registry:file types. By default, the shadcn CLI reads components.json to determine target paths.

registry-item.json target property placeholders

Registry target placeholders resolve to directories configured in components.json and are independent of import prefix. Supported placeholders are: @components/ (resolves to aliases.components), @ui/ (resolves to aliases.ui), @lib/ (resolves to aliases.lib), @hooks/ (resolves to aliases.hooks). Placeholders are only supported at the start of target paths. Unknown placeholders and embedded placeholders are treated as regular paths. @utils/ is not supported because utils points to a file, not a directory.

registry-item.json target property example with placeholders

Example registry item with target placeholders: files contain @ui/button.tsx, @ui/ai/prompt-input.tsx (installs under configured ui directory at ai/prompt-input.tsx), @components/card.tsx, @lib/helper.ts, @hooks/use-demo.ts. A file with type registry:ui can have target @lib/format-date.ts, pointing to a different shadcn directory than the file type.

registry-item.json font property

The font property is required for registry:font items. It configures the font with these fields: family (string, required, CSS font-family value), provider (string, required, currently only 'google' supported), import (string, required, import name from next/font/google), variable (string, required, CSS variable name like --font-sans), weight (string array, optional, font weights to include), subsets (string array, optional, font subsets to include), selector (string, optional, CSS selector to apply font, defaults to 'html'), dependency (string, optional, npm package for non-Next.js projects like @fontsource-variable/inter).

registry-item.json complete example

Example registry-item.json: { '$schema': 'https://ui.shadcn.com/schema/registry-item.json', 'name': 'hello-world', 'type': 'registry:block', 'title': 'Hello World', 'description': 'A simple hello world component.', 'registryDependencies': ['button', '@acme/input-form', 'https://example.com/r/foo'], 'dependencies': ['is-even@3.0.0', 'motion'], 'devDependencies': ['tw-animate-css'], 'files': [{ 'path': 'registry/new-york/hello-world/hello-world.tsx', 'type': 'registry:component' }, { 'path': 'registry/new-york/hello-world/use-hello-world.ts', 'type': 'registry:hook' }], 'cssVars': { 'theme': { 'font-heading': 'Poppins, sans-serif' }, 'light': { 'brand': 'oklch(0.205 0.015 18)' }, 'dark': { 'brand': 'oklch(0.205 0.015 18)' } } }.

registry-item.json cssVars property

The cssVars property defines CSS variables for the registry item. It contains theme, light, and dark objects. For example, theme can define font-heading as 'Poppins, sans-serif', and light/dark objects define color values like brand or radius. This replaces the deprecated tailwind property for Tailwind v4 projects.

registry-item.json meta property

The meta property adds additional metadata to the registry item as key/value pairs. Any key/value pair can be included to be available to the registry item.

registry-item.json categories property

The categories property organizes the registry item. It is an array of strings. For example, ['sidebar', 'dashboard'].

registry-item.json docs property

The docs property shows custom documentation or message when installing the registry item via the CLI. It is a string property.

registry-item.json tailwind property deprecated

The tailwind property is deprecated. Use cssVars.theme instead for Tailwind v4 projects. The tailwind property was used for tailwind configuration like theme, plugins, and content.

registry-item.json css property example

Example css property: '@plugin @tailwindcss/typography': {}, '@layer base': { 'body': { 'font-size': 'var(--text-base)', 'line-height': '1.5' } }, '@layer components': { 'button': { 'background-color': 'var(--color-primary)', 'color': 'var(--color-white)' } }, '@utility text-magic': { 'font-size': 'var(--text-base)', 'line-height': '1.5' }, '@keyframes wiggle': { '0%, 100%': { 'transform': 'rotate(-3deg)' }, '50%': { 'transform': 'rotate(3deg)' } }.

registry-item.json envVars property

The envVars property adds environment variables to the registry item. Variables are added to .env.local or .env file. Existing variables are not overwritten. Use envVars only for development or example variables, never for production variables.

registry-item.json $schema property

The $schema property specifies the JSON Schema for the registry-item.json file. Use the value https://ui.shadcn.com/schema/registry-item.json.

Give your agent this brain