mirror of
https://github.com/shadcn-ui/ui.git
synced 2026-06-11 09:51:40 +00:00
592 lines
13 KiB
Plaintext
592 lines
13 KiB
Plaintext
---
|
|
title: shadcn
|
|
description: Use the shadcn CLI to add components to your project.
|
|
---
|
|
|
|
import { TriangleAlertIcon } from "lucide-react"
|
|
|
|
## init
|
|
|
|
Use the `init` command to initialize configuration and dependencies for an existing project, or create a new project with `--name`.
|
|
|
|
The `init` command installs dependencies, adds the `cn` util and configures CSS variables for the project.
|
|
|
|
```bash
|
|
npx shadcn@latest init
|
|
```
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn init [options] [components...]
|
|
|
|
initialize your project and install dependencies
|
|
|
|
Arguments:
|
|
components names, url or local path to component
|
|
|
|
Options:
|
|
-t, --template <template> the template to use. (next, vite, start, react-router, laravel, astro)
|
|
-b, --base <base> the component library to use. (radix, base)
|
|
-p, --preset [name] use a preset configuration
|
|
-y, --yes skip confirmation prompt. (default: true)
|
|
-d, --defaults use default configuration: --template=next --preset=nova (default: false)
|
|
-f, --force force overwrite of existing configuration. (default: false)
|
|
-c, --cwd <cwd> the working directory. defaults to the current directory.
|
|
-n, --name <name> the name for the new project.
|
|
-s, --silent mute output. (default: false)
|
|
--css-variables use css variables for theming. (default: true)
|
|
--no-css-variables do not use css variables for theming.
|
|
--monorepo scaffold a monorepo project.
|
|
--no-monorepo skip the monorepo prompt.
|
|
--rtl enable RTL support.
|
|
--no-rtl disable RTL support.
|
|
--pointer enable pointer cursor for buttons.
|
|
--no-pointer disable pointer cursor for buttons.
|
|
--reinstall re-install existing UI components.
|
|
--no-reinstall do not re-install existing UI components.
|
|
-h, --help display help for command
|
|
```
|
|
|
|
The `create` command is an alias for `init`:
|
|
|
|
```bash
|
|
npx shadcn@latest create
|
|
```
|
|
|
|
---
|
|
|
|
## add
|
|
|
|
Use the `add` command to add components and dependencies to your project.
|
|
|
|
```bash
|
|
npx shadcn@latest add [component]
|
|
```
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn add [options] [components...]
|
|
|
|
add a component to your project
|
|
|
|
Arguments:
|
|
components name, url or local path to component
|
|
|
|
Options:
|
|
-y, --yes skip confirmation prompt. (default: false)
|
|
-o, --overwrite overwrite existing files. (default: false)
|
|
-c, --cwd <cwd> the working directory. defaults to the current directory.
|
|
-a, --all add all available components (default: false)
|
|
-p, --path <path> the path to add the component to.
|
|
-s, --silent mute output. (default: false)
|
|
--dry-run preview changes without writing files. (default: false)
|
|
--diff [path] show diff for a file.
|
|
--view [path] show file contents.
|
|
-h, --help display help for command
|
|
```
|
|
|
|
---
|
|
|
|
## apply
|
|
|
|
Use the `apply` command to apply a preset to an existing project.
|
|
|
|
```bash
|
|
npx shadcn@latest apply a2r6bw
|
|
```
|
|
|
|
You can apply only the theme or fonts from a preset without reinstalling UI components:
|
|
|
|
```bash
|
|
npx shadcn@latest apply a2r6bw --only theme
|
|
```
|
|
|
|
Supported values for `--only` are `theme` and `font`.
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn apply [options] [preset]
|
|
|
|
apply a preset to an existing project
|
|
|
|
Arguments:
|
|
preset the preset to apply
|
|
|
|
Options:
|
|
--preset <preset> preset configuration to apply
|
|
--only [parts] apply only parts of a preset: theme, font
|
|
-y, --yes skip confirmation prompt. (default: false)
|
|
-c, --cwd <cwd> the working directory. defaults to the current directory.
|
|
-s, --silent mute output. (default: false)
|
|
-h, --help display help for command
|
|
```
|
|
|
|
---
|
|
|
|
## preset
|
|
|
|
Use the `preset` command to inspect preset codes and resolve the preset for an existing project.
|
|
|
|
```bash
|
|
npx shadcn@latest preset decode a2r6bw
|
|
```
|
|
|
|
### preset decode
|
|
|
|
Use `preset decode` to decode a preset code.
|
|
|
|
```bash
|
|
npx shadcn@latest preset decode a2r6bw
|
|
```
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn preset decode [options] <code>
|
|
|
|
decode a preset code
|
|
|
|
Arguments:
|
|
code the preset code to decode
|
|
|
|
Options:
|
|
--json output as JSON. (default: false)
|
|
-h, --help display help for command
|
|
```
|
|
|
|
### preset resolve
|
|
|
|
Use `preset resolve` to resolve the preset from the current project.
|
|
|
|
```bash
|
|
npx shadcn@latest preset resolve
|
|
```
|
|
|
|
The `preset info` command is an alias for `preset resolve`:
|
|
|
|
```bash
|
|
npx shadcn@latest preset info
|
|
```
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn preset resolve|info [options]
|
|
|
|
resolve a preset from your project
|
|
|
|
Options:
|
|
-c, --cwd <cwd> the working directory. defaults to the current directory.
|
|
--json output as JSON. (default: false)
|
|
-h, --help display help for command
|
|
```
|
|
|
|
### preset url
|
|
|
|
Use `preset url` to print the create URL for a preset code.
|
|
|
|
```bash
|
|
npx shadcn@latest preset url a2r6bw
|
|
```
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn preset url [options] <code>
|
|
|
|
get the create URL for a preset code
|
|
|
|
Arguments:
|
|
code the preset code
|
|
|
|
Options:
|
|
-h, --help display help for command
|
|
```
|
|
|
|
### preset open
|
|
|
|
Use `preset open` to open a preset code in the browser.
|
|
|
|
```bash
|
|
npx shadcn@latest preset open a2r6bw
|
|
```
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn preset open [options] <code>
|
|
|
|
open a preset code in the browser
|
|
|
|
Arguments:
|
|
code the preset code
|
|
|
|
Options:
|
|
-h, --help display help for command
|
|
```
|
|
|
|
---
|
|
|
|
## view
|
|
|
|
Use the `view` command to view items from the registry before installing them.
|
|
|
|
```bash
|
|
npx shadcn@latest view [item]
|
|
```
|
|
|
|
You can view multiple items at once:
|
|
|
|
```bash
|
|
npx shadcn@latest view button card dialog
|
|
```
|
|
|
|
Or view items from namespaced registries:
|
|
|
|
```bash
|
|
npx shadcn@latest view @acme/auth @v0/dashboard
|
|
```
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn view [options] <items...>
|
|
|
|
view items from the registry
|
|
|
|
Arguments:
|
|
items the item names or URLs to view
|
|
|
|
Options:
|
|
-c, --cwd <cwd> the working directory. defaults to the current directory.
|
|
-h, --help display help for command
|
|
```
|
|
|
|
---
|
|
|
|
## search
|
|
|
|
Use the `search` command to search for items from registries.
|
|
|
|
```bash
|
|
npx shadcn@latest search [registry]
|
|
```
|
|
|
|
You can search with a query:
|
|
|
|
```bash
|
|
npx shadcn@latest search @shadcn -q "button"
|
|
```
|
|
|
|
Or search multiple registries at once:
|
|
|
|
```bash
|
|
npx shadcn@latest search @shadcn @v0 @acme
|
|
```
|
|
|
|
The `list` command is an alias for `search`:
|
|
|
|
```bash
|
|
npx shadcn@latest list @acme
|
|
```
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn search|list [options] <registries...>
|
|
|
|
search items from registries
|
|
|
|
Arguments:
|
|
registries the registry names or urls to search items from. Names
|
|
must be prefixed with @.
|
|
|
|
Options:
|
|
-c, --cwd <cwd> the working directory. defaults to the current directory.
|
|
-q, --query <query> query string
|
|
-l, --limit <number> maximum number of items to display per registry (default: "100")
|
|
-o, --offset <number> number of items to skip (default: "0")
|
|
-h, --help display help for command
|
|
```
|
|
|
|
---
|
|
|
|
## build
|
|
|
|
Use the `build` command to generate the registry JSON files.
|
|
|
|
```bash
|
|
npx shadcn@latest build
|
|
```
|
|
|
|
This command reads the `registry.json` file and generates the registry JSON files in the `public/r` directory.
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn build [options] [registry]
|
|
|
|
build components for a shadcn registry
|
|
|
|
Arguments:
|
|
registry path to registry.json file (default: "./registry.json")
|
|
|
|
Options:
|
|
-o, --output <path> destination directory for json files (default: "./public/r")
|
|
-c, --cwd <cwd> the working directory. defaults to the current directory.
|
|
-h, --help display help for command
|
|
```
|
|
|
|
To customize the output directory, use the `--output` option.
|
|
|
|
```bash
|
|
npx shadcn@latest build --output ./public/registry
|
|
```
|
|
|
|
---
|
|
|
|
## docs
|
|
|
|
Use the `docs` command to fetch documentation and API references for components.
|
|
|
|
```bash
|
|
npx shadcn@latest docs [component]
|
|
```
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn docs [options] [component]
|
|
|
|
fetch documentation and API references for components
|
|
|
|
Arguments:
|
|
component the component to get docs for
|
|
|
|
Options:
|
|
-c, --cwd <cwd> the working directory. defaults to the current directory.
|
|
-b, --base <base> the base to use either 'base' or 'radix'. defaults to project base.
|
|
--json output as JSON. (default: false)
|
|
-h, --help display help for command
|
|
```
|
|
|
|
---
|
|
|
|
## info
|
|
|
|
Use the `info` command to get information about your project.
|
|
|
|
```bash
|
|
npx shadcn@latest info
|
|
```
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn info [options]
|
|
|
|
get information about your project
|
|
|
|
Options:
|
|
-c, --cwd <cwd> the working directory. defaults to the current directory.
|
|
--json output as JSON. (default: false)
|
|
-h, --help display help for command
|
|
```
|
|
|
|
---
|
|
|
|
## migrate
|
|
|
|
Use the `migrate` command to run migrations on your project.
|
|
|
|
```bash
|
|
npx shadcn@latest migrate [migration]
|
|
```
|
|
|
|
**Available Migrations**
|
|
|
|
| Migration | Description |
|
|
| --------- | ------------------------------------------------------- |
|
|
| `icons` | Migrate your UI components to a different icon library. |
|
|
| `radix` | Migrate to radix-ui. |
|
|
| `rtl` | Migrate your components to support RTL (right-to-left). |
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn migrate [options] [migration] [path]
|
|
|
|
run a migration.
|
|
|
|
Arguments:
|
|
migration the migration to run.
|
|
path optional path or glob pattern to migrate.
|
|
|
|
Options:
|
|
-c, --cwd <cwd> the working directory. defaults to the current directory.
|
|
-l, --list list all migrations. (default: false)
|
|
-y, --yes skip confirmation prompt. (default: false)
|
|
-h, --help display help for command
|
|
```
|
|
|
|
---
|
|
|
|
### migrate rtl
|
|
|
|
The `rtl` migration transforms your components to support RTL (right-to-left) languages.
|
|
|
|
```bash
|
|
npx shadcn@latest migrate rtl
|
|
```
|
|
|
|
This will:
|
|
|
|
1. Update `components.json` to set `rtl: true`
|
|
2. Transform physical CSS properties to logical equivalents (e.g., `ml-4` → `ms-4`, `text-left` → `text-start`)
|
|
3. Add `rtl:` variants where needed (e.g., `space-x-4` → `space-x-4 rtl:space-x-reverse`)
|
|
|
|
**Migrate specific files**
|
|
|
|
You can migrate specific files or use glob patterns:
|
|
|
|
```bash
|
|
# Migrate a specific file
|
|
npx shadcn@latest migrate rtl src/components/ui/button.tsx
|
|
|
|
# Migrate files matching a glob pattern
|
|
npx shadcn@latest migrate rtl "src/components/ui/**"
|
|
```
|
|
|
|
If no path is provided, the migration will transform all files in your `ui` directory (from `components.json`).
|
|
|
|
---
|
|
|
|
### migrate radix
|
|
|
|
The `radix` migration updates your imports from individual `@radix-ui/react-*` packages to the unified `radix-ui` package.
|
|
|
|
```bash
|
|
npx shadcn@latest migrate radix
|
|
```
|
|
|
|
This will:
|
|
|
|
1. Transform imports from `@radix-ui/react-*` to `radix-ui`
|
|
2. Add the `radix-ui` package to your `package.json`
|
|
|
|
**Before**
|
|
|
|
```tsx
|
|
import * as DialogPrimitive from "@radix-ui/react-dialog"
|
|
import * as SelectPrimitive from "@radix-ui/react-select"
|
|
```
|
|
|
|
**After**
|
|
|
|
```tsx
|
|
import { Dialog as DialogPrimitive, Select as SelectPrimitive } from "radix-ui"
|
|
```
|
|
|
|
**Migrate specific files**
|
|
|
|
You can migrate specific files or use glob patterns:
|
|
|
|
```bash
|
|
# Migrate a specific file.
|
|
npx shadcn@latest migrate radix src/components/ui/dialog.tsx
|
|
|
|
# Migrate files matching a glob pattern.
|
|
npx shadcn@latest migrate radix "src/components/ui/**"
|
|
```
|
|
|
|
If no path is provided, the migration will transform all files in your `ui` directory (from `components.json`).
|
|
|
|
Once complete, you can remove any unused `@radix-ui/react-*` packages from your `package.json`.
|
|
|
|
---
|
|
|
|
## eject
|
|
|
|
When you run `init`, shadcn adds `@import "shadcn/tailwind.css"` to your global CSS file. This import provides shared Tailwind v4 utilities such as custom variants (`data-open:`, `data-closed:`, etc.) and accordion animations.
|
|
|
|
Use the `eject` command to inline `shadcn/tailwind.css` into your global CSS file and remove the `shadcn` dependency from your project.
|
|
|
|
<Callout icon={<TriangleAlertIcon />}>
|
|
**Note: This action is irreversible.** After ejecting, future shadcn CLI
|
|
updates to `shadcn/tailwind.css` will not apply automatically.
|
|
</Callout>
|
|
|
|
```bash
|
|
npx shadcn@latest eject
|
|
```
|
|
|
|
**Before**
|
|
|
|
```css
|
|
@import "tailwindcss";
|
|
@import "tw-animate-css";
|
|
@import "shadcn/tailwind.css";
|
|
```
|
|
|
|
**After**
|
|
|
|
```css
|
|
@import "tailwindcss";
|
|
@import "tw-animate-css";
|
|
/* ejected from shadcn@4.8.3 */
|
|
@theme inline {
|
|
@keyframes accordion-down {
|
|
from {
|
|
height: 0;
|
|
}
|
|
to {
|
|
height: var(
|
|
--radix-accordion-content-height,
|
|
var(--accordion-panel-height, auto)
|
|
);
|
|
}
|
|
}
|
|
}
|
|
|
|
@custom-variant data-open {
|
|
&:where([data-state="open"]),
|
|
&:where([data-open]:not([data-open="false"])) {
|
|
@slot;
|
|
}
|
|
}
|
|
|
|
@utility no-scrollbar {
|
|
-ms-overflow-style: none;
|
|
scrollbar-width: none;
|
|
|
|
&::-webkit-scrollbar {
|
|
display: none;
|
|
}
|
|
}
|
|
```
|
|
|
|
**Monorepo**
|
|
|
|
In a monorepo, run the command from the workspace that contains your `components.json` and global CSS file:
|
|
|
|
```bash
|
|
npx shadcn@latest eject -c packages/ui
|
|
```
|
|
|
|
**Options**
|
|
|
|
```bash
|
|
Usage: shadcn eject [options]
|
|
|
|
inline shadcn/tailwind.css and remove the shadcn dependency
|
|
|
|
Options:
|
|
-c, --cwd <cwd> the working directory. defaults to the current directory.
|
|
-y, --yes skip confirmation prompt. (default: false)
|
|
-s, --silent mute output. (default: false)
|
|
-h, --help display help for command
|
|
```
|