laguagu/claude-code-nextjs-skills / skills/shadcn
shadcn
VerifiedManages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", "switch to --preset", and for building a design system or applying a DESIGN.md or brand spec to shadcn/ui.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.1 KB |
| agents/openai.yaml | config | 238 B |
| assets/shadcn-small.png | binary | 1.0 KB |
| assets/shadcn.png | binary | 3.8 KB |
| assets/showcase/color-pair.tsx | other | 3.4 KB |
| assets/showcase/preview-states.css | other | 425 B |
| assets/showcase/state-matrix.tsx | other | 1.6 KB |
| cli.md | markdown | 21.0 KB |
| customization.md | markdown | 6.7 KB |
| design-system-page.md | markdown | 15.4 KB |
| design-system.md | markdown | 21.5 KB |
| evals/evals.json | config | 10.4 KB |
| mcp.md | markdown | 3.5 KB |
| registry.md | markdown | 8.8 KB |
| rules/base-vs-radix.md | markdown | 7.3 KB |
| rules/chat.md | markdown | 17.2 KB |
| rules/composition.md | markdown | 4.8 KB |
| rules/forms.md | markdown | 5.0 KB |
| rules/icons.md | markdown | 1.9 KB |
| rules/styling.md | markdown | 4.6 KB |
| scripts/showcase-coverage.mjs | script | 1.6 KB |
cli.md
View on GitHub# shadcn CLI Reference
Configuration is read from `components.json`.
> Run commands with the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Choose it from the project's lockfile or the `packageManager` field in `package.json`; `info` does not report the package manager. Examples below use `npx shadcn@latest`; substitute the project's runner.
> Use the flags listed here; for an unlisted flag, check the command's `--help` instead of guessing. The CLI auto-detects the package manager from the project's lockfile; there is no `--package-manager` flag.
## Contents
- Commands: init, apply, add (dry-run, smart merge), search, view, docs, diff, info, build, preset, registry
- Templates: next, vite, start, react-router, astro, laravel
- Presets: named, code, URL formats and fields
- Switching presets
---
## Commands
### `init` — Initialize or create a project
```bash
npx shadcn@latest init [components...] [options]
```
Initializes shadcn/ui in an existing project or creates a new project (when `--name` is provided). Optionally installs components in the same step.
| Flag | Short | Description | Default |
| ----------------------- | ----- | --------------------------------------------------------- | ------- |
| `--template <template>` | `-t` | Template (next, vite, start, react-router, astro, laravel) | — |
| `--base <base>` | `-b` | Component library (`base`, `radix` or `aria`) | — |
| `--preset [name]` | `-p` | Preset configuration (named, code, or URL) | — |
| `--yes` | `-y` | Skip confirmation prompt | `true` |
| `--defaults` | `-d` | Use defaults (`--template=next --preset=nova`) | `false` |
| `--force` | `-f` | Force overwrite existing configuration | `false` |
| `--cwd <cwd>` | `-c` | Working directory | current |
| `--name <name>` | `-n` | Name for new project | — |
| `--silent` | `-s` | Mute output | `false` |
| `--rtl` | | Enable RTL support | — |
| `--reinstall` | | Re-install existing UI components | `false` |
| `--no-reinstall` | | Keep existing UI components | — |
| `--monorepo` | | Scaffold a monorepo project | — |
| `--no-monorepo` | | Skip the monorepo prompt | — |
`npx shadcn@latest create` is an alias for `npx shadcn@latest init`.
### `apply` — Apply a preset to an existing project
```bash
npx shadcn@latest apply [preset] [options]
```
Applies a preset to an existing project, overwriting preset-driven config, fonts, CSS variables, and detected UI components.
| Flag | Short | Description | Default |
| ------------------- | ----- | ------------------------------------------ | ------- |
| `--preset <preset>` | — | Preset configuration (named, code, or URL) | — |
| `--only [parts]` | | Apply only `theme`, `font`, or `theme,font` | — |
| `--yes` | `-y` | Skip confirmation prompt | `false` |
| `--cwd <cwd>` | `-c` | Working directory | current |
| `--silent` | `-s` | Mute output | `false` |
`[preset]` is a shorthand for `--preset <preset>`. If both are provided, they must match.
If no preset is provided, the CLI offers to open the custom preset builder on `ui.shadcn.com/create`.
### `add` — Add components
> To compare local components against upstream or to preview changes, use `npx shadcn@latest add <component> --dry-run`, `--diff`, or `--view` rather than fetching raw files from GitHub or other sources: the CLI handles registry resolution, file paths, and CSS diffing automatically.
```bash
npx shadcn@latest add [components...] [options]
```
Accepts component names, registry-prefixed names (`@magicui/shimmer-button`),
GitHub item addresses (`owner/repo/item`), URLs, or local paths.
| Flag | Short | Description | Default |
| --------------- | ----- | -------------------------------------------------------------------------------------------------------------------- | ------- |
| `--yes` | `-y` | Skip confirmation prompt | `false` |
| `--overwrite` | `-o` | Overwrite existing files | `false` |
| `--cwd <cwd>` | `-c` | Working directory | current |
| `--all` | `-a` | Add all available components | `false` |
| `--path <path>` | `-p` | Target path for the component | — |
| `--silent` | `-s` | Mute output | `false` |
| `--dry-run` | | Preview all changes without writing files | `false` |
| `--diff [path]` | | Show diffs. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`) | — |
| `--view [path]` | | Show file contents. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`) | — |
#### Dry-Run Mode
Use `--dry-run` to preview what `add` would do without writing any files. `--diff` and `--view` both imply `--dry-run`.
```bash
# Preview all changes.
npx shadcn@latest add button --dry-run
# Show diffs for all files (top 5).
npx shadcn@latest add button --diff
# Show the diff for a specific file.
npx shadcn@latest add button --diff button.tsx
# Show contents for all files (top 5).
npx shadcn@latest add button --view
# Show the full content of a specific file.
npx shadcn@latest add button --view button.tsx
# Works with URLs too.
npx shadcn@latest add https://api.npoint.io/abc123 --dry-run
# Works with public GitHub registries too.
npx shadcn@latest add owner/repo/item --dry-run
# CSS diffs.
npx shadcn@latest add button --diff globals.css
```
**When to use dry-run:**
- When the user asks "what files will this add?" or "what will this change?" — use `--dry-run`.
- Before overwriting existing components — use `--diff` to preview the changes first.
- When the user wants to inspect component source code without installing — use `--view`.
- When checking what CSS changes would be made to `globals.css` — use `--diff globals.css`.
- When the user asks to review or audit third-party registry code before installing — use `--view` to inspect the source.
> **`npx shadcn@latest add --dry-run` vs `npx shadcn@latest view`:** Prefer `npx shadcn@latest add --dry-run/--diff/--view` over `npx shadcn@latest view` when the user wants to preview changes to their project. `npx shadcn@latest view` only shows raw registry metadata. `npx shadcn@latest add --dry-run` shows exactly what would happen in the user's project: resolved file paths, diffs against existing files, and CSS updates. Use `npx shadcn@latest view` only when the user wants to browse registry info without a project context.
#### Smart Merge from Upstream
See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full workflow.
### `search` — Search registries
```bash
npx shadcn@latest search [registries...] [options]
```
Fuzzy search across registries. Also aliased as `npx shadcn@latest list`.
Supports namespaces (`@acme`), public GitHub registry sources (`owner/repo`),
and registry catalog URLs. Without `-q`, lists all items. When no registries are
passed, searches every registry configured in `components.json`.
| Flag | Short | Description | Default |
| ------------------- | ----- | ------------------------------------------------- | ------- |
| `--query <query>` | `-q` | Search query | — |
| `--type <type>` | `-t` | Filter by item type (e.g. `ui`, `block`, `hook`); comma-separated | — |
| `--limit <number>` | `-l` | Max items to display | `100` |
| `--offset <number>` | `-o` | Items to skip | `0` |
| `--json` | | Output as JSON | `false` |
| `--cwd <cwd>` | `-c` | Working directory | current |
### `view` — View item details
```bash
npx shadcn@latest view <items...> [options]
```
Displays item info including file contents. Examples:
`npx shadcn@latest view @shadcn/button`,
`npx shadcn@latest view owner/repo/item`.
### `docs` — Get component documentation URLs
```bash
npx shadcn@latest docs <components...> [options]
```
Outputs resolved URLs for component documentation, examples, and API references. Accepts one or more component names. Fetch the URLs to get the actual content.
| Flag | Short | Description | Default |
| -------------- | ----- | ------------------------------------------- | ------------ |
| `--base <base>` | `-b` | Component library (`base`, `radix` or `aria`) | project base |
| `--json` | | Output as JSON | `false` |
Example output for `npx shadcn@latest docs input button`:
```
base radix
input
docs https://ui.shadcn.com/docs/components/radix/input
examples https://raw.githubusercontent.com/.../examples/input-example.tsx
button
docs https://ui.shadcn.com/docs/components/radix/button
examples https://raw.githubusercontent.com/.../examples/button-example.tsx
```
Some components include an `api` link to the underlying library (e.g. `cmdk` for the command component).
### `diff` — Check for updates
Do not use this command. Use `npx shadcn@latest add --diff` instead.
### `info` — Project information
```bash
npx shadcn@latest info [options]
```
Displays project info and `components.json` configuration. Run this first to discover the project's framework, aliases, Tailwind version, and resolved paths.
| Flag | Short | Description | Default |
| ------------- | ----- | ----------------- | ------- |
| `--cwd <cwd>` | `-c` | Working directory | current |
| `--json` | | Output as JSON | `false` |
**Project fields** (`project` in `--json`; `null` when no project is detected):
| Field | Type | Meaning |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `framework` | `string` | Framework label (e.g. `Next.js`, `Vite`, `TanStack Start`) |
| `frameworkName` | `string` | Framework id (`next-app`, `next-pages`, `vite`, `react-router`, `tanstack-start`, `astro`, `laravel`, `remix`, `gatsby`, `expo`, `manual`) |
| `frameworkVersion` | `string \| null` | Framework version (e.g. `15.2.4`) |
| `srcDirectory` | `boolean` | Whether the project uses a `src/` directory |
| `rsc` | `boolean` | Whether React Server Components are enabled |
| `typescript` | `boolean` | Whether the project uses TypeScript |
| `tailwindVersion` | `string \| null` | `"v3"` or `"v4"` |
| `tailwindConfig` | `string \| null` | Path to the Tailwind config file |
| `tailwindCss` | `string \| null` | Path to the global CSS file — this is where custom CSS variables go |
| `importAlias` | `string \| null` | Import alias prefix (e.g. `@`, `~`) |
**Configuration fields** (`config` in `--json`, read from `components.json`; `null` when it is missing):
| Field | Type | Meaning |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `style` | `string` | Visual style (e.g. `nova`, `vega`) |
| `base` | `string` | Primitive library (`radix`, `base` or `aria`) — determines component APIs and available props |
| `rsc` | `boolean` | RSC flag from config |
| `typescript` | `boolean` | TypeScript flag (`tsx` in `components.json`) |
| `iconLibrary` | `string \| null` | Icon library — determines icon import package (e.g. `lucide-react`, `@tabler/icons-react`) |
| `rtl` | `boolean` | RTL support |
| `menuColor` | `string \| null` | Menu color |
| `menuAccent` | `string \| null` | Menu accent |
| `aliases.components` | `string` | Component import alias (e.g. `@/components`) |
| `aliases.utils` | `string` | Utils import alias (e.g. `@/lib/utils`) |
| `aliases.ui` | `string \| null` | UI component alias (e.g. `@/components/ui`) |
| `aliases.lib` | `string \| null` | Lib alias (e.g. `@/lib`) |
| `aliases.hooks` | `string \| null` | Hooks alias (e.g. `@/hooks`) |
| `resolvedPaths` | `object` | Absolute paths: `cwd`, `tailwindConfig`, `tailwindCss`, `utils`, `components`, `lib`, `hooks`, `ui` |
| `registries` | `object` | Configured custom registries (name → URL) |
**Top-level fields:** `preset` (resolved preset code and values, or `null`), `components` (installed component names) and `links`. From a monorepo root without `components.json`, `--json` prints `{"error": "monorepo_root", "targets": [...]}`; rerun with `-c <workspace>`.
**Links fields:**
The `info` output includes a **Links** section with templated URLs for component docs, source, and examples. For resolved URLs, use `npx shadcn@latest docs <component>` instead.
### `build` — Build a custom registry
```bash
npx shadcn@latest build [registry] [options]
```
Builds `registry.json` into individual JSON files for distribution. Default input: `./registry.json`, default output: `./public/r`.
For authoring rules, `include`, item definitions, `registryDependencies`, and
GitHub registry behavior, see [registry.md](./registry.md).
| Flag | Short | Description | Default |
| ----------------- | ----- | ----------------- | ------------ |
| `--output <path>` | `-o` | Output directory | `./public/r` |
| `--cwd <cwd>` | `-c` | Working directory | current |
### `preset` — Inspect preset codes
```bash
npx shadcn@latest preset decode <code> [--json] # values of a preset code
npx shadcn@latest preset url <code> # preset builder URL for the code
npx shadcn@latest preset open <code> # open that URL in the browser
npx shadcn@latest preset resolve [--json] [-c <cwd>] # preset of the current project (alias: preset info)
```
### `registry` — Configure and validate registries
```bash
npx shadcn@latest registry add @acme # looks @acme up in the registry index
npx shadcn@latest registry add @acme=https://acme.com/r/{name}.json # explicit URL
npx shadcn@latest registry validate [./registry.json | owner/repo]
```
`registry add` writes the entry to `registries` in `components.json`. It skips namespaces that are already configured and refuses built-in ones such as `@shadcn`. A URL must contain `{name}`. With no argument it opens an interactive picker, so pass the namespace. Registries that need auth `headers` are still configured by editing `components.json` (see [mcp.md](./mcp.md#configuring-registries)). `validate` defaults to `./registry.json`; for authoring rules see [registry.md](./registry.md).
---
## Templates
| Value | Framework | Monorepo support |
| -------------- | -------------- | ---------------- |
| `next` | Next.js | Yes |
| `vite` | Vite | Yes |
| `start` | TanStack Start | Yes |
| `react-router` | React Router | Yes |
| `astro` | Astro | Yes |
| `laravel` | Laravel | No |
All templates except Laravel support monorepo scaffolding via the `--monorepo` flag. Next.js monorepos use `--template next --monorepo`. When passed, the CLI uses a monorepo-specific template directory (e.g. `next-monorepo`, `vite-monorepo`). When neither `--monorepo` nor `--no-monorepo` is passed, the CLI prompts interactively. Laravel does not support monorepo scaffolding.
---
## Presets
Three ways to specify a preset via `--preset`:
1. **Named:** `--preset nova` or `--preset lyra`
2. **Code:** `--preset a2r6bw` (version-prefixed base62 string, e.g. `a2r6bw` or `b0`)
3. **URL:** `--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."`
> Preset codes are opaque: pass them directly to `npx shadcn@latest init --preset <code>` and let the CLI handle resolution, rather than decoding, fetching, or resolving them manually.
> Use `npx shadcn@latest apply --preset <code>` when overwriting an existing project's preset.
## Switching Presets
Ask the user first: **overwrite**, **partial**, **merge**, or **skip** existing components?
- **Overwrite / Re-install** → `npx shadcn@latest apply --preset <code>`. Overwrites all detected component files with the new preset styles. Use when the user hasn't customized components.
- **Partial** → `npx shadcn@latest apply --preset <code> --only theme,font`. Updates only the selected preset parts (`theme`, `font`, or `theme,font`) without reinstalling UI components; `icon` is not supported, because icon changes may need a full component reinstall. Use when the user wants the new theme or fonts but keeps the current components.
- **Merge** → `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to get the list of installed components and use the [smart merge workflow](./SKILL.md#updating-components) to update them one by one, preserving local changes. Use when the user has customized components.
- **Skip** → `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS variables, leaves existing components as-is.
Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base`, `radix` or `aria`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |