Shadcn Vue

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

1. Use existing components first. Use npx shadcn-vue@latest search to check registries before writing custom UI. Check community registries too.
2. Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
3. Use built-in variants before custom styles. variant="outline", size="sm", etc.
4. 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.

Styling & Tailwind → styling.md

• 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 & Inputs → forms.md

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

Component Structure → composition.md

• 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 Components, Not Custom Markup → composition.md

• 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 → icons.md

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

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

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.