mirror of
https://github.com/shadcn-ui/ui.git
synced 2026-06-11 09:51:40 +00:00
7c63c46736
* feat: add github scheme * fix * fix: validate and search * docs: update docs for GitHub registries * docs: add changelog * fix * chore: update announcement * docs(skills): update GitHub registry guidance * fix(registry): reject option-like GitHub refs * fix(registry): limit search registry discovery * fix(registry): bound GitHub validation concurrency * fix(registry): reject whitespace in GitHub refs * fix(registry): track URL dependency sources * test(registry): cover local dependency sources
484 lines
14 KiB
Plaintext
484 lines
14 KiB
Plaintext
---
|
|
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": ["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)"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<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 <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.
|
|
|
|
```json title="registry-item.json" showLineNumbers
|
|
{
|
|
"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.
|
|
|
|
```json title="registry-item.json" showLineNumbers
|
|
{
|
|
"devDependencies": ["tw-animate-css", "name@1.2.0"]
|
|
}
|
|
```
|
|
|
|
### registryDependencies
|
|
|
|
Used for registry dependencies. Each entry is an item address.
|
|
|
|
- For `shadcn/ui` registry items such as `button`, `input`, `select`, etc use the name eg. `['button', 'input', 'select']`.
|
|
- For namespaced registry items, use `@namespace/item-name` eg. `['@acme/input-form']`.
|
|
- For GitHub registry items, use `owner/repo/item-name` eg. `['acme/ui/button']`. For published registries, prefer a tag or full commit SHA eg. `['acme/ui/button#v1.2.0']`.
|
|
- For custom registry items use the URL of the registry item eg. `['https://example.com/r/hello-world.json']`.
|
|
- For local registry item files use a file path eg. `['./hello-world.json']`.
|
|
|
|
```json title="registry-item.json" showLineNumbers
|
|
{
|
|
"registryDependencies": [
|
|
"button",
|
|
"@acme/input-form",
|
|
"acme/ui/button#v1.2.0",
|
|
"https://example.com/r/editor.json",
|
|
"./editor.json"
|
|
]
|
|
}
|
|
```
|
|
|
|
Note: Bare names keep their existing behavior. `button` means the built-in
|
|
shadcn `button` item, not an item from the same GitHub repository. For
|
|
same-repository GitHub dependencies, use the full GitHub item address.
|
|
|
|
Refs are not inherited across dependencies. If a GitHub dependency should be
|
|
reproducible, pin that dependency to its own tag or full commit SHA.
|
|
|
|
See the [GitHub registry](/docs/registry/github) docs for more information.
|
|
|
|
### 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`.
|
|
|
|
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`.
|
|
|
|
```json title="registry-item.json" showLineNumbers
|
|
{
|
|
"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`.
|
|
|
|
```json title="registry-item.json" showLineNumbers
|
|
{
|
|
"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.
|
|
|
|
<Callout>
|
|
`@utils/` is not supported because `utils` points to a file, not a directory.
|
|
</Callout>
|
|
|
|
### 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" }
|
|
}
|
|
```
|