registry-item.json

Specification for registry items.

The registry-item.json schema is used to define your custom registry items.

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)"
    }
  }
}

See more examples

Definitions

You can see the JSON Schema for registry-item.json here.

$schema

The $schema property is used to specify the schema for the registry-item.json file.

registry-item.json

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json"
}

name

The name of the item. This is used to identify the item in the registry. It should be unique for your registry.

registry-item.json

{
  "name": "hello-world"
}

title

A human-readable title for your registry item. Keep it short and descriptive.

registry-item.json

{
  "title": "Hello World"
}

description

A description of your registry item. This can be longer and more detailed than the title.

registry-item.json

{
  "description": "A simple hello world component."
}

type

The type property is used to specify the type of your registry item. This is used to determine the type and target path of the item when resolved for a project.

registry-item.json

{
  "type": "registry:block"
}

The following types are supported:

Type	Description
`registry:base`	Use for entire design systems.
`registry:block`	Use for complex components with multiple files.
`registry:component`	Use for simple components.
`registry:font`	Use for fonts.
`registry:lib`	Use for lib and utils.
`registry:hook`	Use for hooks.
`registry:ui`	Use for UI components and single-file primitives.
`registry:page`	Use for page or file-based routes.
`registry:file`	Use for miscellaneous files.
`registry:style`	Use for registry styles. eg. `new-york`.
`registry:theme`	Use for themes.
`registry:item`	Use for universal registry items.

author

The author property is used to specify the author of the registry item.

It can be unique to the registry item or the same as the author of the registry.

registry-item.json

{
  "author": "John Doe <john@doe.com>"
}

dependencies

The dependencies property is used to specify the dependencies of your registry item. This is for npm packages.

Use @version to specify the version of your registry item.

registry-item.json

{
  "dependencies": [
    "@radix-ui/react-accordion",
    "zod",
    "lucide-react",
    "name@1.0.2"
  ]
}

devDependencies

The devDependencies property is used to specify the dev dependencies of your registry item. These are npm packages that are only needed during development.

Use @version to specify the version of the package.

registry-item.json

{
  "devDependencies": ["tw-animate-css", "name@1.2.0"]
}

registryDependencies

Used for registry dependencies. Can be names, namespaced or URLs.

For shadcn/ui registry items such as button, input, select, etc use the name eg. ['button', 'input', 'select'].
For namespaced registry items such as @acme use the name eg. ['@acme/input-form'].
For custom registry items use the URL of the registry item eg. ['https://example.com/r/hello-world.json'].

registry-item.json

{
  "registryDependencies": [
    "button",
    "@acme/input-form",
    "https://example.com/r/editor.json"
  ]
}

Note: The CLI will automatically resolve remote registry dependencies.

files

The files property is used to specify the files of your registry item. Each file has a path, type and target (optional) property.

The target property is required for registry:page and registry:file types.

registry-item.json

{
  "files": [
    {
      "path": "registry/new-york/hello-world/page.tsx",
      "type": "registry:page",
      "target": "app/hello/page.tsx"
    },
    {
      "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"
    },
    {
      "path": "registry/new-york/hello-world/.env",
      "type": "registry:file",
      "target": "~/.env"
    }
  ]
}

path

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

type

The type property is used to specify the type of the file. See the type section for more information.

target

The target property is used to indicate where the file should be placed in a project. This is optional and only required for registry:page and registry:file types.

By default, the shadcn cli will read a project's components.json file to determine the target path. For some files, such as routes or config you can specify the target path manually.

Use ~ to refer to the root of the project e.g ~/foo.config.js.

You can also use registry target placeholders to place files under the directories configured by the user's components.json. These placeholders are only supported at the start of target and are independent of the project's import prefix. For example, @ui/button.tsx works whether the project imports components with @/, #, package imports or workspace exports.

Placeholder	Resolves to
`@components/`	`aliases.components`
`@ui/`	`aliases.ui`
`@lib/`	`aliases.lib`
`@hooks/`	`aliases.hooks`

Use these placeholders when you want a registry item to install into the project's configured shadcn directories without hardcoding components, src or workspace package paths. Anything after the placeholder is preserved, so @ui/ai/prompt-input.tsx installs under the user's configured ui directory at ai/prompt-input.tsx.

registry-item.json

{
  "files": [
    {
      "path": "registry/new-york/example/button.tsx",
      "type": "registry:ui",
      "target": "@ui/button.tsx"
    },
    {
      "path": "registry/new-york/example/prompt-input.tsx",
      "type": "registry:ui",
      "target": "@ui/ai/prompt-input.tsx"
    },
    {
      "path": "registry/new-york/example/card.tsx",
      "type": "registry:component",
      "target": "@components/card.tsx"
    },
    {
      "path": "registry/new-york/example/helper.ts",
      "type": "registry:lib",
      "target": "@lib/helper.ts"
    },
    {
      "path": "registry/new-york/example/use-demo.ts",
      "type": "registry:hook",
      "target": "@hooks/use-demo.ts"
    }
  ]
}

The target property decides where the file is written. It can point to a different shadcn directory than the file type.

registry-item.json

{
  "files": [
    {
      "path": "registry/new-york/example/format-date.ts",
      "type": "registry:ui",
      "target": "@lib/format-date.ts"
    }
  ]
}

Unknown placeholders are treated as regular target paths. For example, @foo/bar.ts is written as foo/bar.ts. Embedded placeholders such as components/@ui/button.tsx are also treated as regular paths.

@utils/ is not supported because utils points to a file, not a directory.

tailwind

DEPRECATED: Use cssVars.theme instead for Tailwind v4 projects.

The tailwind property is used for tailwind configuration such as theme, plugins and content.

You can use the tailwind.config property to add colors, animations and plugins to your registry item.

registry-item.json

{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "brand": "hsl(var(--brand))"
          },
          "keyframes": {
            "wiggle": {
              "0%, 100%": { "transform": "rotate(-3deg)" },
              "50%": { "transform": "rotate(3deg)" }
            }
          },
          "animation": {
            "wiggle": "wiggle 1s ease-in-out infinite"
          }
        }
      }
    }
  }
}

cssVars

Use to define CSS variables for your registry item.

registry-item.json

{
  "cssVars": {
    "theme": {
      "font-heading": "Poppins, sans-serif"
    },
    "light": {
      "brand": "20 14.3% 4.1%",
      "radius": "0.5rem"
    },
    "dark": {
      "brand": "20 14.3% 4.1%"
    }
  }
}

css

Use css to add new rules to the project's CSS file eg. @layer base, @layer components, @utility, @keyframes, @plugin, etc.

registry-item.json

{
  "css": {
    "@plugin @tailwindcss/typography": {},
    "@plugin foo": {},
    "@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)"
      }
    }
  }
}

envVars

Use envVars to add environment variables to your registry item.

registry-item.json

{
  "envVars": {
    "NEXT_PUBLIC_APP_URL": "http://localhost:4000",
    "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/postgres",
    "OPENAI_API_KEY": ""
  }
}

Environment variables are added to the .env.local or .env file. Existing variables are not overwritten.

IMPORTANT: Use envVars to add development or example variables. Do NOT use it to add production variables.

font

The font property is required for registry:font items. It configures the font family, provider, import name, CSS variable, and the npm package to install for non-Next.js projects.

registry-item.json

{
  "font": {
    "family": "'Inter Variable', sans-serif",
    "provider": "google",
    "import": "Inter",
    "variable": "--font-sans",
    "subsets": ["latin"],
    "dependency": "@fontsource-variable/inter"
  }
}

Property	Type	Required	Description
`family`	`string`	Yes	The CSS font-family value.
`provider`	`string`	Yes	The font provider. Currently only `google` is supported.
`import`	`string`	Yes	The import name for the font from `next/font/google`.
`variable`	`string`	Yes	The CSS variable name for the font (e.g., `--font-sans`, `--font-mono`).
`weight`	`string[]`	No	Array of font weights to include.
`subsets`	`string[]`	No	Array of font subsets to include.
`selector`	`string`	No	CSS selector to apply the font to. Defaults to `html`.
`dependency`	`string`	No	The npm package to install for non-Next.js projects (e.g., `@fontsource-variable/inter`).

docs

Use docs to show custom documentation or message when installing your registry item via the CLI.

registry-item.json

{
  "docs": "To get an OPENAI_API_KEY, sign up for an account at https://platform.openai.com."
}

registry-item.json

Definitions

$schema

name

title

description

type

author

dependencies

devDependencies

registryDependencies

files

path

type

target

tailwind

cssVars

css

envVars

font

docs

categories

meta