111k
新建

示例

PreviousNext

注册表 item 的示例：样式、组件、css vars 等。

registry:style

扩展 shadcn/ui 的自定义样式

下面这个注册表 item 是一个扩展 shadcn/ui 的自定义样式。在执行 npx shadcn init 时，它会：

  • 安装 @tabler/icons-react 作为依赖。
  • 将 login-01 block 和 calendar 组件添加到项目中。
  • 从远程注册表添加 editor。
  • 将 font-sans 变量设置为 Inter, sans-serif。
  • 在浅色和深色模式下安装 brand 颜色。
example-style.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "example-style",
  "type": "registry:style",
  "dependencies": ["@tabler/icons-react"],
  "registryDependencies": [
    "login-01",
    "calendar",
    "https://example.com/r/editor.json"
  ],
  "cssVars": {
    "theme": {
      "font-sans": "Inter, sans-serif"
    },
    "light": {
      "brand": "20 14.3% 4.1%"
    },
    "dark": {
      "brand": "20 14.3% 4.1%"
    }
  }
}

从零开始的自定义样式

下面这个注册表 item 是一个不扩展 shadcn/ui 的自定义样式。请看 extends: none 字段。

它可以用于从零创建一个新样式，也就是自定义组件、css vars、依赖等。

在执行 npx shadcn add 时，它会：

  • 安装 tailwind-merge 和 clsx 作为依赖。
  • 从 shadcn/ui 注册表添加 utils registry item。
  • 从远程注册表添加 button、input、label 和 select 组件。
  • 安装新的 css vars：main、bg、border、text、ring。
example-style.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:theme

自定义主题

example-theme.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-theme",
  "type": "registry:theme",
  "cssVars": {
    "light": {
      "background": "oklch(1 0 0)",
      "foreground": "oklch(0.141 0.005 285.823)",
      "primary": "oklch(0.546 0.245 262.881)",
      "primary-foreground": "oklch(0.97 0.014 254.604)",
      "ring": "oklch(0.746 0.16 232.661)",
      "sidebar-primary": "oklch(0.546 0.245 262.881)",
      "sidebar-primary-foreground": "oklch(0.97 0.014 254.604)",
      "sidebar-ring": "oklch(0.746 0.16 232.661)"
    },
    "dark": {
      "background": "oklch(1 0 0)",
      "foreground": "oklch(0.141 0.005 285.823)",
      "primary": "oklch(0.707 0.165 254.624)",
      "primary-foreground": "oklch(0.97 0.014 254.604)",
      "ring": "oklch(0.707 0.165 254.624)",
      "sidebar-primary": "oklch(0.707 0.165 254.624)",
      "sidebar-primary-foreground": "oklch(0.97 0.014 254.604)",
      "sidebar-ring": "oklch(0.707 0.165 254.624)"
    }
  }
}

自定义颜色

下面这个样式会先使用 shadcn/ui 的默认值初始化，然后再添加一个自定义的 brand 颜色。

example-style.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-style",
  "type": "registry:style",
  "cssVars": {
    "light": {
      "brand": "oklch(0.99 0.00 0)"
    },
    "dark": {
      "brand": "oklch(0.14 0.00 286)"
    }
  }
}

registry:block

自定义 block

这个 block 会安装来自 shadcn/ui 注册表的 login-01 block。

login-01.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "login-01",
  "type": "registry:block",
  "description": "A simple login form.",
  "registryDependencies": ["button", "card", "input", "label"],
  "files": [
    {
      "path": "blocks/login-01/page.tsx",
      "content": "import { LoginForm } ...",
      "type": "registry:page",
      "target": "app/login/page.tsx"
    },
    {
      "path": "blocks/login-01/components/login-form.tsx",
      "content": "...",
      "type": "registry:component"
    }
  ]
}

安装 block 并覆盖原语

你可以从 shadcn/ui 注册表安装一个 block，并用你自己的自定义原语覆盖它。

在执行 npx shadcn add 时，它会：

  • 添加来自 shadcn/ui 注册表的 login-01 block。
  • 用远程注册表中的 button、input 和 label 原语覆盖它们。
example-style.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-login",
  "type": "registry:block",
  "registryDependencies": [
    "login-01",
    "https://example.com/r/button.json",
    "https://example.com/r/input.json",
    "https://example.com/r/label.json"
  ]
}

registry:ui

UI 组件

registry:ui item 是一个可复用的 UI 组件。它可以包含依赖、注册表依赖和 CSS 变量。

button.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "button",
  "type": "registry:ui",
  "dependencies": ["radix-ui"],
  "files": [
    {
      "path": "ui/button.tsx",
      "content": "...",
      "type": "registry:ui"
    }
  ]
}

带 CSS 变量的 UI 组件

sidebar.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "sidebar",
  "type": "registry:ui",
  "dependencies": ["radix-ui"],
  "registryDependencies": ["button", "separator", "sheet", "tooltip"],
  "files": [
    {
      "path": "ui/sidebar.tsx",
      "content": "...",
      "type": "registry:ui"
    }
  ],
  "cssVars": {
    "light": {
      "sidebar-background": "oklch(0.985 0 0)",
      "sidebar-foreground": "oklch(0.141 0.005 285.823)",
      "sidebar-border": "oklch(0.92 0.004 286.32)"
    },
    "dark": {
      "sidebar-background": "oklch(0.141 0.005 285.823)",
      "sidebar-foreground": "oklch(0.985 0 0)",
      "sidebar-border": "oklch(0.274 0.006 286.033)"
    }
  }
}

registry:lib

工具库

registry:lib item 是一个工具库。你可以用它来共享辅助函数、常量或其他非组件代码。

utils.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "utils",
  "type": "registry:lib",
  "dependencies": ["clsx", "tailwind-merge"],
  "files": [
    {
      "path": "lib/utils.ts",
      "content": "import { clsx, type ClassValue } from \"clsx\"\nimport { twMerge } from \"tailwind-merge\"\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs))\n}",
      "type": "registry:lib"
    }
  ]
}

registry:hook

自定义 hook

registry:hook item 是一个自定义 React hook。

use-mobile.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "use-mobile",
  "type": "registry:hook",
  "files": [
    {
      "path": "hooks/use-mobile.ts",
      "content": "...",
      "type": "registry:hook"
    }
  ]
}

带依赖的 hook

use-debounce.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "use-debounce",
  "type": "registry:hook",
  "dependencies": ["react"],
  "files": [
    {
      "path": "hooks/use-debounce.ts",
      "content": "...",
      "type": "registry:hook"
    }
  ]
}

registry:font

自定义字体

registry:font item 会安装一个 Google 字体。font 字段是必需的，用来配置字体族、提供方、导入名和 CSS 变量。

font-inter.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "font-inter",
  "type": "registry:font",
  "font": {
    "family": "'Inter Variable', sans-serif",
    "provider": "google",
    "import": "Inter",
    "variable": "--font-sans",
    "subsets": ["latin"],
    "dependency": "@fontsource-variable/inter"
  }
}

等宽字体

font-jetbrains-mono.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "font-jetbrains-mono",
  "type": "registry:font",
  "font": {
    "family": "'JetBrains Mono Variable', monospace",
    "provider": "google",
    "import": "JetBrains_Mono",
    "variable": "--font-mono",
    "weight": ["400", "500", "600", "700"],
    "subsets": ["latin"],
    "dependency": "@fontsource-variable/jetbrains-mono"
  }
}

衬线字体

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

带自定义选择器的字体

使用 selector 字段可以把字体应用到特定 CSS 选择器，而不是全局应用到 html。这对于标题字体或其他定向字体应用很有用。

font-playfair-display.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "font-playfair-display",
  "type": "registry:font",
  "font": {
    "family": "'Playfair Display Variable', serif",
    "provider": "google",
    "import": "Playfair_Display",
    "variable": "--font-heading",
    "subsets": ["latin"],
    "selector": "h1, h2, h3, h4, h5, h6",
    "dependency": "@fontsource-variable/playfair-display"
  }
}

当设置了 selector 时，字体工具类（例如 font-heading）会通过 CSS @apply 应用到 @layer base 中指定的选择器，而不是添加到 <html> 元素上。CSS 变量仍然会注入到 <html> 上，因此全局都可用。

registry:base

自定义 base

registry:base item 是一个完整的设计系统基础。它定义了项目所需的全部依赖、CSS 变量和配置。config 字段是 registry:base item 独有的。

config 字段接受以下属性（全部可选）：

PropertyTypeDescription
stylestringThe style name for the base.
iconLibrarystringThe icon library to use (e.g. lucide).
rscbooleanWhether to enable React Server Components. Defaults to false.
tsxbooleanWhether to use TypeScript. Defaults to true.
rtlbooleanWhether to enable right-to-left support. Defaults to false.
menuColor"default" | "inverted" | "default-translucent" | "inverted-translucent"The menu color scheme. Defaults to "default".
menuAccent"subtle" | "bold"The menu accent style. Defaults to "subtle".
tailwind.baseColorstringThe base color name (e.g. neutral, slate, zinc).
tailwind.cssstringPath to the Tailwind CSS file.
tailwind.prefixstringA prefix to add to all Tailwind classes.
aliases.componentsstringImport alias for components.
aliases.utilsstringImport alias for utilities.
aliases.uistringImport alias for UI components.
aliases.libstringImport alias for lib.
aliases.hooksstringImport alias for hooks.
registriesRecord<string, string | object>Custom registry URLs. Keys must start with @.
custom-base.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-base",
  "type": "registry:base",
  "config": {
    "style": "custom-base",
    "iconLibrary": "lucide",
    "tailwind": {
      "baseColor": "neutral"
    }
  },
  "dependencies": [
    "class-variance-authority",
    "tw-animate-css",
    "lucide-react"
  ],
  "registryDependencies": ["utils", "font-inter"],
  "cssVars": {
    "light": {
      "background": "oklch(1 0 0)",
      "foreground": "oklch(0.141 0.005 285.823)",
      "primary": "oklch(0.21 0.006 285.885)",
      "primary-foreground": "oklch(0.985 0 0)"
    },
    "dark": {
      "background": "oklch(0.141 0.005 285.823)",
      "foreground": "oklch(0.985 0 0)",
      "primary": "oklch(0.985 0 0)",
      "primary-foreground": "oklch(0.21 0.006 285.885)"
    }
  },
  "css": {
    "@import \"tw-animate-css\"": {},
    "@layer base": {
      "*": {
        "@apply border-border outline-ring/50": {}
      },
      "body": {
        "@apply bg-background text-foreground": {}
      }
    }
  }
}

从零创建 base

使用 extends: none 可以创建一个不继承 shadcn/ui 默认值的 base。

custom-base.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "my-design-system",
  "extends": "none",
  "type": "registry:base",
  "config": {
    "style": "my-design-system",
    "iconLibrary": "lucide",
    "tailwind": {
      "baseColor": "slate"
    }
  },
  "dependencies": ["tailwind-merge", "clsx", "tw-animate-css", "lucide-react"],
  "registryDependencies": ["utils", "font-geist"],
  "cssVars": {
    "light": {
      "background": "oklch(1 0 0)",
      "foreground": "oklch(0.141 0.005 285.823)"
    },
    "dark": {
      "background": "oklch(0.141 0.005 285.823)",
      "foreground": "oklch(0.985 0 0)"
    }
  }
}

常用字段

作者

使用 author 字段为你的注册表 item 添加署名。

example-item.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-component",
  "type": "registry:ui",
  "author": "shadcn",
  "files": [
    {
      "path": "ui/custom-component.tsx",
      "content": "...",
      "type": "registry:ui"
    }
  ]
}

开发依赖

使用 devDependencies 字段把包安装为开发依赖。

example-item.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-item",
  "type": "registry:item",
  "devDependencies": ["@types/mdx"],
  "files": [
    {
      "path": "lib/mdx.ts",
      "content": "...",
      "type": "registry:lib"
    }
  ]
}

元数据

使用 meta 字段为你的注册表 item 附加任意元数据。它可以用来存储工具或脚本可使用的自定义数据。

example-item.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-component",
  "type": "registry:ui",
  "meta": {
    "category": "forms",
    "version": "2.0.0"
  },
  "files": [
    {
      "path": "ui/custom-component.tsx",
      "content": "...",
      "type": "registry:ui"
    }
  ]
}

CSS 变量

自定义主题变量

把自定义主题变量添加到 theme 对象中。

example-theme.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-theme",
  "type": "registry:theme",
  "cssVars": {
    "theme": {
      "font-heading": "Inter, sans-serif",
      "shadow-card": "0 0 0 1px rgba(0, 0, 0, 0.1)"
    }
  }
}

覆盖 Tailwind CSS 变量

example-theme.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-theme",
  "type": "registry:theme",
  "cssVars": {
    "theme": {
      "spacing": "0.2rem",
      "breakpoint-sm": "640px",
      "breakpoint-md": "768px",
      "breakpoint-lg": "1024px",
      "breakpoint-xl": "1280px",
      "breakpoint-2xl": "1536px"
    }
  }
}

添加自定义 CSS

基础样式

example-base.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-style",
  "type": "registry:style",
  "css": {
    "@layer base": {
      "h1": {
        "font-size": "var(--text-2xl)"
      },
      "h2": {
        "font-size": "var(--text-xl)"
      }
    }
  }
}

组件

example-card.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-card",
  "type": "registry:component",
  "css": {
    "@layer components": {
      "card": {
        "background-color": "var(--color-white)",
        "border-radius": "var(--rounded-lg)",
        "padding": "var(--spacing-6)",
        "box-shadow": "var(--shadow-xl)"
      }
    }
  }
}

添加自定义工具类

简单工具类

example-component.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-component",
  "type": "registry:component",
  "css": {
    "@utility content-auto": {
      "content-visibility": "auto"
    }
  }
}

复杂工具类

example-utility.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-component",
  "type": "registry:component",
  "css": {
    "@utility scrollbar-hidden": {
      "scrollbar-hidden": {
        "&::-webkit-scrollbar": {
          "display": "none"
        }
      }
    }
  }
}

函数式工具类

example-functional.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-component",
  "type": "registry:component",
  "css": {
    "@utility tab-*": {
      "tab-size": "var(--tab-size-*)"
    }
  }
}

添加 CSS 导入

使用 @import 可以给你的注册表 item 添加 CSS 导入。导入语句会放在 CSS 文件顶部。

Basic import

example-import.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-import",
  "type": "registry:component",
  "css": {
    "@import \"tailwindcss\"": {},
    "@import \"./styles/base.css\"": {}
  }
}

Import with url() syntax

example-url-import.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "font-import",
  "type": "registry:item",
  "css": {
    "@import url(\"https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap\")": {},
    "@import url('./local-styles.css')": {}
  }
}

Import with media queries

example-media-import.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "responsive-import",
  "type": "registry:item",
  "css": {
    "@import \"print-styles.css\" print": {},
    "@import url(\"mobile.css\") screen and (max-width: 768px)": {}
  }
}

Add custom plugins

Use @plugin to add Tailwind plugins to your registry item. Plugins will be automatically placed after imports and before other content.

Important: When using plugins from npm packages, you must also add them to the dependencies array.

Basic plugin usage

example-plugin.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "custom-plugin",
  "type": "registry:item",
  "css": {
    "@plugin \"@tailwindcss/typography\"": {},
    "@plugin \"foo\"": {}
  }
}

Plugin with npm dependency

When using plugins from npm packages like @tailwindcss/typography, include them in the dependencies.

example-typography.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 plugins

example-scoped-plugin.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "scoped-plugins",
  "type": "registry:component",
  "css": {
    "@plugin \"@headlessui/tailwindcss\"": {},
    "@plugin \"tailwindcss/plugin\"": {},
    "@plugin \"./custom-plugin.js\"": {}
  }
}

Multiple plugins with automatic ordering

When you add multiple plugins, they are automatically grouped together and deduplicated.

example-multiple-plugins.json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "multiple-plugins",
  "type": "registry:item",
  "dependencies": [
    "@tailwindcss/typography",
    "@tailwindcss/forms",
    "tw-animate-css"
  ],
  "css": {
    "@plugin \"@tailwindcss/typography\"": {},
    "@plugin \"@tailwindcss/forms\"": {},
    "@plugin \"tw-animate-css\"": {}
  }
}

Combined imports and plugins

When using both @import and @plugin directives, imports are placed first, followed by plugins, then other CSS content.

example-combined.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"
    }
  }
}

Add custom animations

Note: you need to define both @keyframes in css and theme in cssVars to use animations.

example-component.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)"
      }
    }
  }
}

Add environment variables

You can add environment variables using the envVars field.

example-item.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": ""
  }
}

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

Universal Items

As of 2.9.0, you can create universal items that can be installed without framework detection or components.json.

To make an item universal i.e framework agnostic, all the files in the item must have an explicit target.

Here's an example of a registry item that installs custom Cursor rules for python:

.cursor/rules/custom-python.mdc
{
  "$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": "..."
    }
  ]
}

Here's another example for installing a custom ESLint config:

.eslintrc.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": "..."
    }
  ]
}

You can also have a universal item that installs multiple files:

my-custom-starter-template.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": "..."
    }
  ]
}