shadcn-vue
A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.
IMPORTANT: Run all CLI commands using the project's package runner: npx shadcn-vue@latest, pnpm dlx shadcn-vue@latest, or bunx --bun shadcn-vue@latest — based on the project's packageManager. Examples below use npx shadcn-vue@latest but substitute the correct runner for the project.
Current Project Context
!`npx shadcn-vue@latest info --json`
The JSON above contains the project config and installed components. Use npx shadcn-vue@latest docs <component> to get documentation and example URLs for any component.
Principles
- Use existing components first. Use
npx shadcn-vue@latest search to check registries before writing custom UI. Check community registries too.
- Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
- Use built-in variants before custom styles.
variant="outline", size="sm", etc.
- Use semantic colors.
bg-primary, text-muted-foreground — never raw values like bg-blue-500.
Critical Rules
These rules are always enforced. Each links to a file with Incorrect/Correct code pairs.
class for layout, not styling. Never override component colors or typography.
- No
space-x-* or space-y-*. Use flex with gap-*. For vertical stacks, flex flex-col gap-*.
- Use
size-* when width and height are equal. size-10 not w-10 h-10.
- Use
truncate shorthand. Not overflow-hidden text-ellipsis whitespace-nowrap.
- No manual
dark: color overrides. Use semantic tokens (bg-background, text-muted-foreground).
- Use
cn() for conditional classes. Don't write manual template literal ternaries.
- No manual
z-index on overlay components. Dialog, Sheet, Popover, etc. handle their own stacking.
- Forms use
FieldGroup + Field. Never use raw div with space-y-* or grid gap-* for form layout.
InputGroup uses InputGroupInput/InputGroupTextarea. Never raw Input/Textarea inside InputGroup.
- Buttons inside inputs use
InputGroup + InputGroupAddon.
- Option sets (2–7 choices) use
ToggleGroup. Don't loop Button with manual active state.
FieldSet + FieldLegend for grouping related checkboxes/radios. Don't use a div with a heading.
- Field validation uses
data-invalid + aria-invalid. data-invalid on Field, aria-invalid on the control. For disabled: data-disabled on Field, disabled on the control.
- Items always inside their Group.
SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
- Dialog, Sheet, and Drawer always need a Title.
DialogTitle, SheetTitle, DrawerTitle required for accessibility. Use class="sr-only" if visually hidden.
- Use full Card composition.
CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Don't dump everything in CardContent.
- Button has no
isPending/isLoading. Compose with Spinner + data-icon + disabled.
TabsTrigger must be inside TabsList. Never render triggers directly in Tabs.
Avatar always needs AvatarFallback. For when the image fails to load.
- Use existing components before custom markup. Check if a component exists before writing a styled
div.
- Callouts use
Alert. Don't build custom styled divs.
- Empty states use
Empty. Don't build custom empty state markup.
- Toast via
vue-sonner. Use toast() from vue-sonner.
- Use
Separator instead of <hr> or <div class="border-t">.
- Use
Skeleton for loading placeholders. No custom animate-pulse divs.
- Use
Badge instead of custom styled spans.
- Icons in
Button use data-icon. data-icon="inline-start" or data-icon="inline-end" on the icon.
- No sizing classes on icons inside components. Components handle icon sizing via CSS. No
size-4 or w-4 h-4.
- Pass icons as objects, not string keys.
:icon="CheckIcon", not a string lookup.
- Use project's
iconLibrary for imports. Check iconLibrary from project context. Never assume @lucide/vue.
CLI
- Apply preset codes directly with the CLI. Use
npx shadcn-vue@latest apply <code> for existing projects, or npx shadcn-vue@latest init --preset <code> when initializing.
Key Patterns
These are the most common patterns that differentiate correct shadcn-vue code. For edge cases, see the linked rule files above.
<!-- Form layout: FieldGroup + Field, not div + Label. -->
<FieldGroup>
<Field>
<FieldLabel for="email">Email</FieldLabel>
<Input id="email" />
</Field>
</FieldGroup>
<!-- Validation: data-invalid on Field, aria-invalid on the control. -->
<Field data-invalid>
<FieldLabel>Email</FieldLabel>
<Input aria-invalid />
<FieldDescription>Invalid email.</FieldDescription>
</Field>
<!-- Icons in buttons: data-icon, no sizing classes. -->
<Button>
<SearchIcon data-icon="inline-start" />
Search
</Button>
<!-- Spacing: gap-*, not space-y-*. -->
<div class="flex flex-col gap-4"> <!-- correct -->
<div class="space-y-4"> <!-- wrong -->
<!-- Equal dimensions: size-*, not w-* h-*. -->
<Avatar class="size-10"> <!-- correct -->
<Avatar class="w-10 h-10"> <!-- wrong -->
<!-- Status colors: Badge variants or semantic tokens, not raw colors. -->
<Badge variant="secondary">+20.1%</Badge> <!-- correct -->
<span class="text-emerald-600">+20.1%</span> <!-- wrong -->
Component Selection
| Need |
Use |
| Button/action |
Button with appropriate variant |
| Form inputs |
Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, Slider |
| Toggle between 2–7 options |
ToggleGroup + ToggleGroupItem |
| Data display |
Table, Card, Badge, Avatar |
| Navigation |
Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination |
| Overlays |
Dialog (modal), Sheet (side panel), Drawer (bottom sheet), AlertDialog (confirmation) |
| Feedback |
vue-sonner (toast), Alert, Progress, Skeleton, Spinner |
| Command palette |
Command inside Dialog |
| Charts |
Chart (wraps Unovis) |
| Layout |
Card, Separator, Resizable, ScrollArea, Accordion, Collapsible |
| Empty states |
Empty |
| Menus |
DropdownMenu, ContextMenu, Menubar |
| Tooltips/info |
Tooltip, HoverCard, Popover |
Key Fields
The injected project context contains these key fields:
aliases → use the actual alias prefix for imports (e.g. @/, ~/), never hardcode.
tailwindVersion → "v4" uses @theme inline blocks; "v3" uses tailwind.config.js.
tailwindCssFile → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
style → component visual treatment (e.g. nova, vega).
base → primitive library (reka). Affects component APIs and available props.
iconLibrary → determines icon imports. Use @lucide/vue for lucide, @tabler/icons-vue for tabler, etc. Never assume @lucide/vue.
resolvedPaths → exact file-system destinations for components, utils, hooks, etc.
framework → routing and file conventions (e.g. Nuxt vs Vite SPA).
packageManager → use this for any non-shadcn-vue dependency installs (e.g. pnpm add date-fns vs npm install date-fns).
See cli.md — info command for the full field reference.
Component Docs, Examples, and Usage
Run npx shadcn-vue@latest docs <component> to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
npx shadcn-vue@latest docs button dialog select
When creating, fixing, debugging, or using a component, always run npx shadcn-vue@latest docs and fetch the URLs first. This ensures you're working with the correct API and usage patterns rather than guessing.
For per-component documentation, see components/<component>.md in this skill (70 components auto-generated from the official repo).
Workflow
- Get project context — already injected above. Run
npx shadcn-vue@latest info again if you need to refresh.
- Check installed components first — before running
add, always check the components list from project context or list the resolvedPaths.ui directory. Don't import components that haven't been added, and don't re-add ones already installed.
- Find components —
npx shadcn-vue@latest search.
- Get docs and examples — run
npx shadcn-vue@latest docs <component> to get URLs, then fetch them. Use npx shadcn-vue@latest view to browse registry items you haven't installed. To preview changes to installed components, use npx shadcn-vue@latest add --diff.
- Install or update —
npx shadcn-vue@latest add. When updating existing components, use --dry-run and --diff to preview changes first (see Updating Components below).
- Fix imports in third-party components — After adding components from community registries, check the added non-UI files for hardcoded import paths like
@/components/ui/.... These won't match the project's actual aliases. Use npx shadcn-vue@latest info to get the correct ui alias (e.g. @workspace/ui/components) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
- Review added components — After adding a component or block from any registry, always read the added files and verify they are correct. Check for missing sub-components (e.g.
SelectItem without SelectGroup), missing imports, incorrect composition, or violations of the Critical Rules. Also replace any icon imports with the project's iconLibrary from the project context (e.g. if the registry item uses @lucide/vue but the project uses hugeicons, swap the imports and icon names accordingly). Fix all issues before moving on.
- Registry must be explicit — When the user asks to add a block or component, do not guess the registry. If no registry is specified (e.g. user says "add a login block" without specifying
@shadcn, etc.), ask which registry to use. Never default to a registry on behalf of the user.
- Switching presets — Ask the user first: overwrite, merge, or skip?
- Overwrite:
npx shadcn-vue@latest apply <code>. Overwrites detected components, fonts, and CSS variables.
- Merge:
npx shadcn-vue@latest init --preset <code> --force --no-reinstall, then run npx shadcn-vue@latest info to list installed components, then for each installed component use --dry-run and --diff to smart merge it individually.
- Skip:
npx shadcn-vue@latest init --preset <code> --force --no-reinstall. Only updates config and CSS, leaves components as-is.
- Important: 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 (reka) 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.
Updating Components
When the user asks to update a component from upstream while keeping their local changes, use --dry-run and --diff to intelligently merge. NEVER fetch raw files from GitHub manually — always use the CLI.
- Run
npx shadcn-vue@latest add <component> --dry-run to see all files that would be affected.
- For each file, run
npx shadcn-vue@latest add <component> --diff <file> to see what changed upstream vs local.
- Decide per file based on the diff:
- No local changes → safe to overwrite.
- Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
- User says "just update everything" → use
--overwrite, but confirm first.
- Never use
--overwrite without the user's explicit approval.
Quick Reference
# Create a new project.
npx shadcn-vue@latest init --name my-app --preset nova
npx shadcn-vue@latest init --name my-app --preset a2r6bw --template vite
# Initialize existing project.
npx shadcn-vue@latest init --preset nova
npx shadcn-vue@latest init --defaults # shortcut: --template=nuxt --preset=nova (base style implied)
# Apply a preset to an existing project.
npx shadcn-vue@latest apply a2r6bw
# Add components.
npx shadcn-vue@latest add button card dialog
npx shadcn-vue@latest add --all
# Search registries.
npx shadcn-vue@latest search @shadcn -q "sidebar"
# Get component docs and example URLs.
npx shadcn-vue@latest docs button dialog select
# View registry item details (for items not yet installed).
npx shadcn-vue@latest view @shadcn/button
# Get project info.
npx shadcn-vue@latest info
npx shadcn-vue@latest info --json
Named presets: nova, vega, maia, lyra, mira, luma
Templates: nuxt, vite, astro, laravel
Preset codes: Version-prefixed base62 strings (e.g. a2r6bw), from shadcn-vue.com.
Quick Start (3 Minutes)
For Vue Projects (Vite)
1. Initialize shadcn-vue
npx shadcn-vue@latest init
During initialization:
- Style:
New York or Default (cannot change later!)
- Base color:
Slate (recommended)
- CSS variables:
Yes (required for dark mode)
2. Configure TypeScript Path Aliases
// tsconfig.json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
}
}
3. Configure Vite
// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import tailwindcss from "@tailwindcss/vite"; // Tailwind v4
import path from "path";
export default defineConfig({
plugins: [vue(), tailwindcss()],
resolve: {
alias: {
"@": path.resolve(__dirname, "./src"),
},
},
});
4. Add Your First Component
npx shadcn-vue@latest add button
Bundled Resources
Templates (templates/):
quick-setup.ts - Complete setup guide for Vue/Nuxt with examples (190 lines)
References (references/):
cli.md - CLI commands, flags, presets, templates, smart merge
theming.md - Theming and cssVariables
error-catalog.md - All 7 documented issues with solutions (267 lines)
component-examples.md - All 50+ component examples with code
dark-mode-setup.md - Complete dark mode implementation guide
data-tables.md - Data tables with TanStack Table
Rules (references/rules/):
styling.md - Semantic colors, variants, class, spacing, size, truncate, dark mode, cn(), z-index
forms.md - FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
composition.md - Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
icons.md - data-icon, icon sizing, passing icons as objects, iconLibrary
Component Documentation (components/):
references/components.md - Index of all shadcn-vue components (70)
components/<component>.md - Individual component documentation with installation, usage, and examples
Official Documentation:
When to Load References
Load these references based on the task:
Load references/rules/styling.md when:
- Writing or reviewing component markup with Tailwind classes
- User encounters styling issues or inconsistent appearance
- Need to verify correct use of semantic tokens, spacing, sizing
- Trigger phrases: "style", "color", "spacing", "gap", "dark mode", "class"
Load references/rules/forms.md when:
- Building forms or working with form controls
- User needs accessible form field patterns
- Working with InputGroup, ToggleGroup, FieldSet, or validation states
- Trigger phrases: "form", "input", "field", "validation", "toggle group"
Load references/rules/composition.md when:
- Composing multiple components together
- Building dialogs, cards, menus, tabs, or overlay components
- User asks which component to use for a given UI pattern
- Trigger phrases: "dialog", "card", "tabs", "menu", "overlay", "empty state", "alert"
Load references/rules/icons.md when:
- Adding icons to buttons or other components
- Troubleshooting icon sizing or alignment issues
- Need to determine correct icon import package
- Trigger phrases: "icon", "lucide", "tabler", "data-icon"
Load references/error-catalog.md when:
- User encounters "component not found" or import errors
- Setup commands fail or configuration issues arise
- Tailwind CSS variables or TypeScript paths broken
- Trigger phrases: "not working", "error", "fails to", "broken"
Load references/components.md when:
- User asks what components are available (names, categories, status)
- User needs to add/use a component and wants the correct install/import paths
- You need to confirm a component exists before recommending a custom build
Load references/component-examples.md when:
- User asks "how do I implement [component]?"
- Need copy-paste examples for specific components
- Building forms, tables, navigation, or data display
- Trigger phrases: "example", "how to use", "implement", "code sample"
Load references/cli.md when:
- User asks how to run the CLI (
init, add, update, search, view, docs, info, apply) or what prompts mean
- Need the exact command/flags for installing one or more components
- Working with presets, templates, or switching presets
- Troubleshooting CLI-related issues (registry, paths, overwrites)
Load references/dark-mode-setup.md when:
- Implementing dark mode / theme switching
- User mentions Vue 3 + Vite, Nuxt, or Astro setup
- Need composable patterns for theme management
- Trigger phrases: "dark mode", "theme", "light/dark", "color scheme"
Load references/theming.md when:
- User wants to customize theme tokens via CSS variables (
cssVariables, :root, .dark)
- Need to wire Tailwind to CSS-variable-based colors and radii
- Setting up/adjusting design tokens (colors, radius, typography) for shadcn-vue
Load references/data-tables.md when:
- Building sortable/filterable/paginated tables
- User mentions TanStack Table or
DataTable
- Trigger phrases: "data table", "table", "tanstack", "sorting", "pagination"
Critical Setup Rules
Always Do
✅ Run init before adding components
- Creates required configuration and utilities
- Sets up path aliases
✅ Use CSS variables for theming (cssVariables: true)
- Enables dark mode support
- Flexible theme customization
✅ Configure TypeScript path aliases
- Required for component imports
- Must match
components.json aliases
✅ Keep components.json in version control
- Team members need same configuration
- Documents project setup
Never Do
❌ Don't change style after initialization
- Requires complete reinstall
- Reinitialize in new directory instead
❌ Don't mix Radix Vue and Reka UI v2
- Incompatible component APIs
- Use one or the other
❌ Don't skip TypeScript configuration
- Component imports will fail
- IDE autocomplete won't work
❌ Don't use without Tailwind CSS
- Components are styled with Tailwind
- Won't render correctly
Common Mistakes
- Running
add before init and missing components.json.
- Using CSS variable classes without
tailwind.cssVariables: true.
- Hardcoding
@/ imports instead of reading aliases from project context.
- Fetching component files from GitHub manually instead of using the CLI.
- Using
--overwrite without user confirmation.
- Guessing registry names instead of asking the user.
Configuration
shadcn-vue uses components.json to configure:
- Component paths (
@/components/ui)
- Utils location (
@/lib/utils)
- Tailwind config paths
- TypeScript paths
- Icon library
- Custom registries
Full example: See templates/components.json or generate via npx shadcn-vue@latest init
Utils Library
The @/lib/utils.ts file provides the cn() helper for merging Tailwind classes:
- Combines multiple className strings
- Uses
clsx + tailwind-merge for conflict resolution
Auto-generated by shadcn-vue init - no manual setup needed.
1---
2name: shadcn-vue
3description: shadcn-vue for Vue/Nuxt with Reka UI components and Tailwind. Use for accessible UI, Auto Form, data tables, charts, dark mode, or encountering component imports, Reka UI errors.
4metadata:
5 source: https://skillmd.com/skills/noartem/shadcn-vue
6---
7
8# shadcn-vue
9
10A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.
11
12> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn-vue@latest`, `pnpm dlx shadcn-vue@latest`, or `bunx --bun shadcn-vue@latest` — based on the project's `packageManager`. Examples below use `npx shadcn-vue@latest` but substitute the correct runner for the project.
13
14## Current Project Context
15
16```json
17!`npx shadcn-vue@latest info --json`
18```
19
20The JSON above contains the project config and installed components. Use `npx shadcn-vue@latest docs <component>` to get documentation and example URLs for any component.
21
22## Principles
23
241. **Use existing components first.** Use `npx shadcn-vue@latest search` to check registries before writing custom UI. Check community registries too.
252. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
263. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc.
274. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.
28
29## Critical Rules
30
31These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
32
33### Styling & Tailwind → [rules/styling.md](./references/rules/styling.md)
34
35- **`class` for layout, not styling.** Never override component colors or typography.
36- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`.
37- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`.
38- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`.
39- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`).
40- **Use `cn()` for conditional classes.** Don't write manual template literal ternaries.
41- **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking.
42
43### Forms & Inputs → [rules/forms.md](./references/rules/forms.md)
44
45- **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout.
46- **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`.
47- **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.**
48- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.
49- **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading.
50- **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control.
51
52### Component Structure → [rules/composition.md](./references/rules/composition.md)
53
54- **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.
55- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `class="sr-only"` if visually hidden.
56- **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`.
57- **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`.
58- **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`.
59- **`Avatar` always needs `AvatarFallback`.** For when the image fails to load.
60
61### Use Components, Not Custom Markup → [rules/composition.md](./references/rules/composition.md)
62
63- **Use existing components before custom markup.** Check if a component exists before writing a styled `div`.
64- **Callouts use `Alert`.** Don't build custom styled divs.
65- **Empty states use `Empty`.** Don't build custom empty state markup.
66- **Toast via `vue-sonner`.** Use `toast()` from `vue-sonner`.
67- **Use `Separator`** instead of `<hr>` or `<div class="border-t">`.
68- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.
69- **Use `Badge`** instead of custom styled spans.
70
71### Icons → [rules/icons.md](./references/rules/icons.md)
72
73- **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon.
74- **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`.
75- **Pass icons as objects, not string keys.** `:icon="CheckIcon"`, not a string lookup.
76- **Use project's `iconLibrary` for imports.** Check `iconLibrary` from project context. Never assume `@lucide/vue`.
77
78### CLI
79
80- **Apply preset codes directly with the CLI.** Use `npx shadcn-vue@latest apply <code>` for existing projects, or `npx shadcn-vue@latest init --preset <code>` when initializing.
81
82## Key Patterns
83
84These are the most common patterns that differentiate correct shadcn-vue code. For edge cases, see the linked rule files above.
85
86```html
87<!-- Form layout: FieldGroup + Field, not div + Label. -->
88<FieldGroup>
89 <Field>
90 <FieldLabel for="email">Email</FieldLabel>
91 <Input id="email" />
92 </Field>
93</FieldGroup>
94
95<!-- Validation: data-invalid on Field, aria-invalid on the control. -->
96<Field data-invalid>
97 <FieldLabel>Email</FieldLabel>
98 <Input aria-invalid />
99 <FieldDescription>Invalid email.</FieldDescription>
100</Field>
101
102<!-- Icons in buttons: data-icon, no sizing classes. -->
103<Button>
104 <SearchIcon data-icon="inline-start" />
105 Search
106</Button>
107
108<!-- Spacing: gap-*, not space-y-*. -->
109<div class="flex flex-col gap-4"> <!-- correct -->
110<div class="space-y-4"> <!-- wrong -->
111
112<!-- Equal dimensions: size-*, not w-* h-*. -->
113<Avatar class="size-10"> <!-- correct -->
114<Avatar class="w-10 h-10"> <!-- wrong -->
115
116<!-- Status colors: Badge variants or semantic tokens, not raw colors. -->
117<Badge variant="secondary">+20.1%</Badge> <!-- correct -->
118<span class="text-emerald-600">+20.1%</span> <!-- wrong -->
119```
120
121## Component Selection
122
123| Need | Use |
124| -------------------------- | --------------------------------------------------------------------------------------------------- |
125| Button/action | `Button` with appropriate variant |
126| Form inputs | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |
127| Toggle between 2–7 options | `ToggleGroup` + `ToggleGroupItem` |
128| Data display | `Table`, `Card`, `Badge`, `Avatar` |
129| Navigation | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination` |
130| Overlays | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation) |
131| Feedback | `vue-sonner` (toast), `Alert`, `Progress`, `Skeleton`, `Spinner` |
132| Command palette | `Command` inside `Dialog` |
133| Charts | `Chart` (wraps Unovis) |
134| Layout | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible` |
135| Empty states | `Empty` |
136| Menus | `DropdownMenu`, `ContextMenu`, `Menubar` |
137| Tooltips/info | `Tooltip`, `HoverCard`, `Popover` |
138
139## Key Fields
140
141The injected project context contains these key fields:
142
143- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode.
144- **`tailwindVersion`** → `"v4"` uses `@theme inline` blocks; `"v3"` uses `tailwind.config.js`.
145- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
146- **`style`** → component visual treatment (e.g. `nova`, `vega`).
147- **`base`** → primitive library (`reka`). Affects component APIs and available props.
148- **`iconLibrary`** → determines icon imports. Use `@lucide/vue` for `lucide`, `@tabler/icons-vue` for `tabler`, etc. Never assume `@lucide/vue`.
149- **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc.
150- **`framework`** → routing and file conventions (e.g. Nuxt vs Vite SPA).
151- **`packageManager`** → use this for any non-shadcn-vue dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`).
152
153See [cli.md — `info` command](./references/cli.md#info--project-information) for the full field reference.
154
155## Component Docs, Examples, and Usage
156
157Run `npx shadcn-vue@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
158
159```bash
160npx shadcn-vue@latest docs button dialog select
161```
162
163**When creating, fixing, debugging, or using a component, always run `npx shadcn-vue@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.
164
165For per-component documentation, see `components/<component>.md` in this skill (70 components auto-generated from the official repo).
166
167## Workflow
168
1691. **Get project context** — already injected above. Run `npx shadcn-vue@latest info` again if you need to refresh.
1702. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed.
1713. **Find components** — `npx shadcn-vue@latest search`.
1724. **Get docs and examples** — run `npx shadcn-vue@latest docs <component>` to get URLs, then fetch them. Use `npx shadcn-vue@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn-vue@latest add --diff`.
1735. **Install or update** — `npx shadcn-vue@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).
1746. **Fix imports in third-party components** — After adding components from community registries, check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn-vue@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
1757. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `@lucide/vue` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on.
1768. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, etc.), ask which registry to use. Never default to a registry on behalf of the user.
1779. **Switching presets** — Ask the user first: **overwrite**, **merge**, or **skip**?
178 - **Overwrite**: `npx shadcn-vue@latest apply <code>`. Overwrites detected components, fonts, and CSS variables.
179 - **Merge**: `npx shadcn-vue@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn-vue@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually.
180 - **Skip**: `npx shadcn-vue@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS, leaves components as-is.
181 - **Important**: 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 (`reka`) 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.
182
183## Updating Components
184
185When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.**
186
1871. Run `npx shadcn-vue@latest add <component> --dry-run` to see all files that would be affected.
1882. For each file, run `npx shadcn-vue@latest add <component> --diff <file>` to see what changed upstream vs local.
1893. Decide per file based on the diff:
190 - No local changes → safe to overwrite.
191 - Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
192 - User says "just update everything" → use `--overwrite`, but confirm first.
1934. **Never use `--overwrite` without the user's explicit approval.**
194
195## Quick Reference
196
197```bash
198# Create a new project.
199npx shadcn-vue@latest init --name my-app --preset nova
200npx shadcn-vue@latest init --name my-app --preset a2r6bw --template vite
201
202# Initialize existing project.
203npx shadcn-vue@latest init --preset nova
204npx shadcn-vue@latest init --defaults # shortcut: --template=nuxt --preset=nova (base style implied)
205
206# Apply a preset to an existing project.
207npx shadcn-vue@latest apply a2r6bw
208
209# Add components.
210npx shadcn-vue@latest add button card dialog
211npx shadcn-vue@latest add --all
212
213# Search registries.
214npx shadcn-vue@latest search @shadcn -q "sidebar"
215
216# Get component docs and example URLs.
217npx shadcn-vue@latest docs button dialog select
218
219# View registry item details (for items not yet installed).
220npx shadcn-vue@latest view @shadcn/button
221
222# Get project info.
223npx shadcn-vue@latest info
224npx shadcn-vue@latest info --json
225```
226
227**Named presets:** `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`
228**Templates:** `nuxt`, `vite`, `astro`, `laravel`
229**Preset codes:** Version-prefixed base62 strings (e.g. `a2r6bw`), from [shadcn-vue.com](https://shadcn-vue.com).
230
231---
232
233## Quick Start (3 Minutes)
234
235### For Vue Projects (Vite)
236
237#### 1. Initialize shadcn-vue
238
239```bash
240npx shadcn-vue@latest init
241```
242
243**During initialization**:
244
245- Style: `New York` or `Default` (cannot change later!)
246- Base color: `Slate` (recommended)
247- CSS variables: `Yes` (required for dark mode)
248
249#### 2. Configure TypeScript Path Aliases
250
251```json
252// tsconfig.json
253{
254 "compilerOptions": {
255 "baseUrl": ".",
256 "paths": {
257 "@/*": ["./src/*"]
258 }
259 }
260}
261```
262
263#### 3. Configure Vite
264
265```typescript
266// vite.config.ts
267import { defineConfig } from "vite";
268import vue from "@vitejs/plugin-vue";
269import tailwindcss from "@tailwindcss/vite"; // Tailwind v4
270import path from "path";
271
272export default defineConfig({
273 plugins: [vue(), tailwindcss()],
274 resolve: {
275 alias: {
276 "@": path.resolve(__dirname, "./src"),
277 },
278 },
279});
280```
281
282#### 4. Add Your First Component
283
284```bash
285npx shadcn-vue@latest add button
286```
287
288---
289
290## Bundled Resources
291
292**Templates** (`templates/`):
293
294- `quick-setup.ts` - Complete setup guide for Vue/Nuxt with examples (190 lines)
295
296**References** (`references/`):
297
298- `cli.md` - CLI commands, flags, presets, templates, smart merge
299- `theming.md` - Theming and `cssVariables`
300- `error-catalog.md` - All 7 documented issues with solutions (267 lines)
301- `component-examples.md` - All 50+ component examples with code
302- `dark-mode-setup.md` - Complete dark mode implementation guide
303- `data-tables.md` - Data tables with TanStack Table
304
305**Rules** (`references/rules/`):
306
307- `styling.md` - Semantic colors, variants, class, spacing, size, truncate, dark mode, cn(), z-index
308- `forms.md` - FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
309- `composition.md` - Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
310- `icons.md` - data-icon, icon sizing, passing icons as objects, iconLibrary
311
312**Component Documentation** (`components/`):
313
314- `references/components.md` - Index of all shadcn-vue components (70)
315- `components/<component>.md` - Individual component documentation with installation, usage, and examples
316
317**Official Documentation**:
318
319- shadcn-vue Docs: https://shadcn-vue.com
320- Reka UI Docs: https://reka-ui.com
321- GitHub: https://github.com/unovue/shadcn-vue
322
323---
324
325## When to Load References
326
327Load these references based on the task:
328
3291. **Load `references/rules/styling.md` when:**
330 - Writing or reviewing component markup with Tailwind classes
331 - User encounters styling issues or inconsistent appearance
332 - Need to verify correct use of semantic tokens, spacing, sizing
333 - **Trigger phrases:** "style", "color", "spacing", "gap", "dark mode", "class"
334
3352. **Load `references/rules/forms.md` when:**
336 - Building forms or working with form controls
337 - User needs accessible form field patterns
338 - Working with InputGroup, ToggleGroup, FieldSet, or validation states
339 - **Trigger phrases:** "form", "input", "field", "validation", "toggle group"
340
3413. **Load `references/rules/composition.md` when:**
342 - Composing multiple components together
343 - Building dialogs, cards, menus, tabs, or overlay components
344 - User asks which component to use for a given UI pattern
345 - **Trigger phrases:** "dialog", "card", "tabs", "menu", "overlay", "empty state", "alert"
346
3474. **Load `references/rules/icons.md` when:**
348 - Adding icons to buttons or other components
349 - Troubleshooting icon sizing or alignment issues
350 - Need to determine correct icon import package
351 - **Trigger phrases:** "icon", "lucide", "tabler", "data-icon"
352
3535. **Load `references/error-catalog.md` when:**
354 - User encounters "component not found" or import errors
355 - Setup commands fail or configuration issues arise
356 - Tailwind CSS variables or TypeScript paths broken
357 - **Trigger phrases:** "not working", "error", "fails to", "broken"
358
3596. **Load `references/components.md` when:**
360 - User asks what components are available (names, categories, status)
361 - User needs to add/use a component and wants the correct install/import paths
362 - You need to confirm a component exists before recommending a custom build
363
3647. **Load `references/component-examples.md` when:**
365 - User asks "how do I implement [component]?"
366 - Need copy-paste examples for specific components
367 - Building forms, tables, navigation, or data display
368 - **Trigger phrases:** "example", "how to use", "implement", "code sample"
369
3708. **Load `references/cli.md` when:**
371 - User asks how to run the CLI (`init`, `add`, `update`, `search`, `view`, `docs`, `info`, `apply`) or what prompts mean
372 - Need the exact command/flags for installing one or more components
373 - Working with presets, templates, or switching presets
374 - Troubleshooting CLI-related issues (registry, paths, overwrites)
375
3769. **Load `references/dark-mode-setup.md` when:**
377 - Implementing dark mode / theme switching
378 - User mentions Vue 3 + Vite, Nuxt, or Astro setup
379 - Need composable patterns for theme management
380 - **Trigger phrases:** "dark mode", "theme", "light/dark", "color scheme"
381
38210. **Load `references/theming.md` when:**
383 - User wants to customize theme tokens via CSS variables (`cssVariables`, `:root`, `.dark`)
384 - Need to wire Tailwind to CSS-variable-based colors and radii
385 - Setting up/adjusting design tokens (colors, radius, typography) for shadcn-vue
386
38711. **Load `references/data-tables.md` when:**
388 - Building sortable/filterable/paginated tables
389 - User mentions TanStack Table or `DataTable`
390 - **Trigger phrases:** "data table", "table", "tanstack", "sorting", "pagination"
391
392---
393
394## Critical Setup Rules
395
396### Always Do
397
398✅ **Run `init` before adding components**
399
400- Creates required configuration and utilities
401- Sets up path aliases
402
403✅ **Use CSS variables for theming** (`cssVariables: true`)
404
405- Enables dark mode support
406- Flexible theme customization
407
408✅ **Configure TypeScript path aliases**
409
410- Required for component imports
411- Must match `components.json` aliases
412
413✅ **Keep components.json in version control**
414
415- Team members need same configuration
416- Documents project setup
417
418### Never Do
419
420❌ **Don't change `style` after initialization**
421
422- Requires complete reinstall
423- Reinitialize in new directory instead
424
425❌ **Don't mix Radix Vue and Reka UI v2**
426
427- Incompatible component APIs
428- Use one or the other
429
430❌ **Don't skip TypeScript configuration**
431
432- Component imports will fail
433- IDE autocomplete won't work
434
435❌ **Don't use without Tailwind CSS**
436
437- Components are styled with Tailwind
438- Won't render correctly
439
440---
441
442## Common Mistakes
443
444- Running `add` before `init` and missing `components.json`.
445- Using CSS variable classes without `tailwind.cssVariables: true`.
446- Hardcoding `@/` imports instead of reading `aliases` from project context.
447- Fetching component files from GitHub manually instead of using the CLI.
448- Using `--overwrite` without user confirmation.
449- Guessing registry names instead of asking the user.
450
451---
452
453## Configuration
454
455shadcn-vue uses `components.json` to configure:
456
457- Component paths (`@/components/ui`)
458- Utils location (`@/lib/utils`)
459- Tailwind config paths
460- TypeScript paths
461- Icon library
462- Custom registries
463
464**Full example:** See `templates/components.json` or generate via `npx shadcn-vue@latest init`
465
466---
467
468## Utils Library
469
470The `@/lib/utils.ts` file provides the `cn()` helper for merging Tailwind classes:
471
472- Combines multiple className strings
473- Uses `clsx` + `tailwind-merge` for conflict resolution
474
475**Auto-generated** by `shadcn-vue init` - no manual setup needed.