shadcn/apps/v4/content/docs/registry/registry-item-json.mdx

---
title: registry-item.json
description: Specification for registry items.
---

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

```json title="registry-item.json" showLineNumbers
{
  "$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": ["[email protected]", "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)"
    }
  }
}
```

<div className="mt-6 flex items-center gap-2">
  <Link href="/docs/registry/examples">See more examples</Link>
</div>

## Definitions

You can see the JSON Schema for `registry-item.json` [here](https://ui.shadcn.com/schema/registry-item.json).

### $schema

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

```json title="registry-item.json" showLineNumbers
{
  "$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.

```json title="registry-item.json" showLineNumbers
{
  "name": "hello-world"
}
```

### title

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

```json title="registry-item.json" showLineNumbers
{
  "title": "Hello World"
}
```

### description

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

```json title="registry-item.json" showLineNumbers
{
  "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.

```json title="registry-item.json" showLineNumbers
{
  "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.

```json title="registry-item.json" showLineNumbers
{
  "author": "John Doe <[email protected]>"
}
```

### 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.

```json title="registry-item.json" showLineNumbers
{
  "dependencies": [
    "@radix-ui/react-accordion",
    "zod",
    "lucide-react",
    "[email protected]"
  ]
}
```

### 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.

```json title="registry-item.json" showLineNumbers
{
  "devDependencies": ["tw-animate-css", "[email protected]"]
}
```

### 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']`.

```json title="registry-item.json" showLineNumbers
{
  "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.**

```json title="registry-item.json" showLineNumbers
{
  "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](#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`.

### 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.

```json title="registry-item.json" showLineNumbers
{
  "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.

```json title="registry-item.json" showLineNumbers
{
  "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.

```json title="registry-item.json" showLineNumbers
{
  "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.

```json title="registry-item.json" showLineNumbers
{
  "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.

<Callout>

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

</Callout>

### 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.

```json title="registry-item.json" showLineNumbers
{
  "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.

```json title="registry-item.json" showLineNumbers
{
  "docs": "To get an OPENAI_API_KEY, sign up for an account at https://platform.openai.com."
}
```

### categories

Use `categories` to organize your registry item.

```json title="registry-item.json" showLineNumbers
{
  "categories": ["sidebar", "dashboard"]
}
```

### meta

Use `meta` to add additional metadata to your registry item. You can add any key/value pair that you want to be available to the registry item.

```json title="registry-item.json" showLineNumbers
{
  "meta": { "foo": "bar" }
}
```