Skip to content

laguagu/claude-code-nextjs-skills / skills/shadcn

shadcn

Verified

Manages 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.

FileKindSize
SKILL.mdskill md22.1 KB
agents/openai.yamlconfig238 B
assets/shadcn-small.pngbinary1.0 KB
assets/shadcn.pngbinary3.8 KB
assets/showcase/color-pair.tsxother3.4 KB
assets/showcase/preview-states.cssother425 B
assets/showcase/state-matrix.tsxother1.6 KB
cli.mdmarkdown21.0 KB
customization.mdmarkdown6.7 KB
design-system-page.mdmarkdown15.4 KB
design-system.mdmarkdown21.5 KB
evals/evals.jsonconfig10.4 KB
mcp.mdmarkdown3.5 KB
registry.mdmarkdown8.8 KB
rules/base-vs-radix.mdmarkdown7.3 KB
rules/chat.mdmarkdown17.2 KB
rules/composition.mdmarkdown4.8 KB
rules/forms.mdmarkdown5.0 KB
rules/icons.mdmarkdown1.9 KB
rules/styling.mdmarkdown4.6 KB
scripts/showcase-coverage.mjsscript1.6 KB
# 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.
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall