mirror of
https://github.com/shadcn-ui/ui.git
synced 2026-06-24 05:05:44 +00:00
600 lines
15 KiB
Plaintext
600 lines
15 KiB
Plaintext
---
|
|
title: Examples
|
|
description: "Examples of registry items: styles, components, css vars, etc."
|
|
---
|
|
|
|
## registry:style
|
|
|
|
### Custom style that extends shadcn/ui
|
|
|
|
The following registry item is a custom style that extends shadcn/ui. On `npx shadcn init`, it will:
|
|
|
|
- Install `@tabler/icons-react` as a dependency.
|
|
- Add the `login-01` block and `calendar` component to the project.
|
|
- Add the `editor` from a remote registry.
|
|
- Set the `font-sans` variable to `Inter, sans-serif`.
|
|
- Install a `brand` color in light and dark mode.
|
|
|
|
```json title="example-style.json" showLineNumbers
|
|
{
|
|
"$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%"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Custom style from scratch
|
|
|
|
The following registry item is a custom style that doesn't extend shadcn/ui. See the `extends: none` field.
|
|
|
|
It can be used to create a new style from scratch i.e custom components, css vars, dependencies, etc.
|
|
|
|
On `npx shadcn add`, the following will:
|
|
|
|
- Install `tailwind-merge` and `clsx` as dependencies.
|
|
- Add the `utils` registry item from the shadcn/ui registry.
|
|
- Add the `button`, `input`, `label`, and `select` components from a remote registry.
|
|
- Install new css vars: `main`, `bg`, `border`, `text`, `ring`.
|
|
|
|
```json title="example-style.json" showLineNumbers
|
|
{
|
|
"$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
|
|
|
|
### Custom theme
|
|
|
|
```json title="example-theme.json" showLineNumbers
|
|
{
|
|
"$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)"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Custom colors
|
|
|
|
The following style will init using shadcn/ui defaults and then add a custom `brand` color.
|
|
|
|
```json title="example-style.json" showLineNumbers
|
|
{
|
|
"$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
|
|
|
|
### Custom block
|
|
|
|
This blocks installs the `login-01` block from the shadcn/ui registry.
|
|
|
|
```json title="login-01.json" showLineNumbers
|
|
{
|
|
"$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"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Install a block and override primitives
|
|
|
|
You can install a block fromt the shadcn/ui registry and override the primitives using your custom ones.
|
|
|
|
On `npx shadcn add`, the following will:
|
|
|
|
- Add the `login-01` block from the shadcn/ui registry.
|
|
- Override the `button`, `input`, and `label` primitives with the ones from the remote registry.
|
|
|
|
```json title="example-style.json" showLineNumbers
|
|
{
|
|
"$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"
|
|
]
|
|
}
|
|
```
|
|
|
|
## CSS Variables
|
|
|
|
### Custom Theme Variables
|
|
|
|
Add custom theme variables to the `theme` object.
|
|
|
|
```json title="example-theme.json" showLineNumbers
|
|
{
|
|
"$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)"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Override Tailwind CSS variables
|
|
|
|
```json title="example-theme.json" showLineNumbers
|
|
{
|
|
"$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"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Add custom CSS
|
|
|
|
### Base styles
|
|
|
|
```json title="example-base.json" showLineNumbers
|
|
{
|
|
"$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)"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Components
|
|
|
|
```json title="example-card.json" showLineNumbers
|
|
{
|
|
"$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)"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Add custom utilities
|
|
|
|
### Simple utility
|
|
|
|
```json title="example-component.json" showLineNumbers
|
|
{
|
|
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
|
|
"name": "custom-component",
|
|
"type": "registry:component",
|
|
"css": {
|
|
"@utility content-auto": {
|
|
"content-visibility": "auto"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Complex utility
|
|
|
|
```json title="example-utility.json" showLineNumbers
|
|
{
|
|
"$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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Functional utilities
|
|
|
|
```json title="example-functional.json" showLineNumbers
|
|
{
|
|
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
|
|
"name": "custom-component",
|
|
"type": "registry:component",
|
|
"css": {
|
|
"@utility tab-*": {
|
|
"tab-size": "var(--tab-size-*)"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Add CSS imports
|
|
|
|
Use `@import` to add CSS imports to your registry item. The imports will be placed at the top of the CSS file.
|
|
|
|
### Basic import
|
|
|
|
```json title="example-import.json" showLineNumbers
|
|
{
|
|
"$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
|
|
|
|
```json title="example-url-import.json" showLineNumbers
|
|
{
|
|
"$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
|
|
|
|
```json title="example-media-import.json" showLineNumbers
|
|
{
|
|
"$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
|
|
|
|
```json title="example-plugin.json" showLineNumbers
|
|
{
|
|
"$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.
|
|
|
|
```json title="example-typography.json" showLineNumbers
|
|
{
|
|
"$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
|
|
|
|
```json title="example-scoped-plugin.json" showLineNumbers
|
|
{
|
|
"$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.
|
|
|
|
```json title="example-multiple-plugins.json" showLineNumbers
|
|
{
|
|
"$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.
|
|
|
|
```json title="example-combined.json" showLineNumbers
|
|
{
|
|
"$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.
|
|
|
|
```json title="example-component.json" showLineNumbers
|
|
{
|
|
"$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.
|
|
|
|
```json title="example-item.json" showLineNumbers {5-9}
|
|
{»
|
|
"$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.
|
|
|
|
<Callout>
|
|
|
|
**IMPORTANT:** Use `envVars` to add development or example variables. Do NOT use it to add production variables.
|
|
|
|
</Callout>
|
|
|
|
## 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_:
|
|
|
|
```json title=".cursor/rules/custom-python.mdc" showLineNumbers {9}
|
|
{
|
|
"$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 installation custom ESLint config:
|
|
|
|
```json title=".eslintrc.json" showLineNumbers {9}
|
|
{
|
|
"$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:
|
|
|
|
```json title="my-custom-starter-template.json" showLineNumbers {9}
|
|
{
|
|
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
|
|
"name": "my-custom-start-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": "..."
|
|
}
|
|
]
|
|
}
|
|
```
|