description:Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI. 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", or "switch to --preset".
The JSON above contains the project config and installed components. Use `npx shadcn@latest docs <component>` to get documentation and example URLs for any component.
Run `npx shadcn@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
Run all CLI commands using the project's package runner:
`
npx shadcn@latest
`
,
`
pnpm dlx shadcn@latest
`
, or
`
bunx --bun shadcn@latest
`
— based on the project's
`
packageManager
`
. Examples below use
`
npx shadcn@latest
`
but substitute the correct runner for the project.
`
npx shadcn@latest search
`
to check registries before writing custom UI. Check community registries too.
`
variant="outline"
`
,
`
size="sm"
`
, etc.
`
bg-primary
`
,
`
text-muted-foreground
`
— never raw values like
`
bg-blue-500
`
.
styling.md
]
(
./rules/styling.md
)
for layout, not styling.
**
Never override component colors or typography.
`
or
`
space-y-*
`
.
**
Use
`
flex
`
with
`
gap-*
`
. For vertical stacks,
`
flex flex-col gap-*
`
.
`
when width and height are equal.
**
`
size-10
`
not
`
w-10 h-10
`
.
`
shorthand.
**
Not
`
overflow-hidden text-ellipsis whitespace-nowrap
`
.
`
color overrides.
**
Use semantic tokens (
`
bg-background
`
,
`
text-muted-foreground
`
).
`
for conditional classes.
**
Don't write manual template literal ternaries.
`
on overlay components.
**
Dialog, Sheet, Popover, etc. handle their own stacking.
forms.md
]
(
./rules/forms.md
)
`
+
`
Field
`
.
**
Never use raw
`
div
`
with
`
space-y-*
`
or
`
grid gap-*
`
for form layout.
uses
`
InputGroupInput
`
/
`
InputGroupTextarea
`
.
**
Never raw
`
Input
`
/
`
Textarea
`
inside
`
InputGroup
`
.
`
+
`
InputGroupAddon
`
.
**
`
.
**
Don't loop
`
Button
`
with manual active state.
+
`
FieldLegend
`
for grouping related checkboxes/radios.
**
Don't use a
`
div
`
with a heading.
`
+
`
aria-invalid
`
.
**
`
data-invalid
`
on
`
Field
`
,
`
aria-invalid
`
on the control. For disabled:
`
data-disabled
`
on
`
Field
`
,
`
disabled
`
on the control.
composition.md
]
(
./rules/composition.md
)
`
SelectItem
`
→
`
SelectGroup
`
.
`
DropdownMenuItem
`
→
`
DropdownMenuGroup
`
.
`
CommandItem
`
→
`
CommandGroup
`
.
`
(radix) or
`
render
`
(base) for custom triggers.
**
Check
`
base
`
field from
`
npx shadcn@latest info
`
. →
[
base-vs-radix.md
]
(
./rules/base-vs-radix.md
)
`
DialogTitle
`
,
`
SheetTitle
`
,
`
DrawerTitle
`
required for accessibility. Use
`
className="sr-only"
`
if visually hidden.
`
CardHeader
`
/
`
CardTitle
`
/
`
CardDescription
`
/
`
CardContent
`
/
`
CardFooter
`
. Don't dump everything in
`
CardContent
`
.
`
/
`
isLoading
`
.
**
Compose with
`
Spinner
`
+
`
data-icon
`
+
`
disabled
`
.
must be inside
`
TabsList
`
.
**
Never render triggers directly in
`
Tabs
`
.
always needs
`
AvatarFallback
`
.
**
For when the image fails to load.
composition.md
]
(
./rules/composition.md
)
`
div
`
.
`
.
**
Don't build custom styled divs.
`
.
**
Don't build custom empty state markup.
`
.
**
Use
`
toast()
`
from
`
sonner
`
.
`
**
instead of
`
<hr>
`
or
`
<div className="border-t">
`
.
`
**
for loading placeholders. No custom
`
animate-pulse
`
divs.
`
**
instead of custom styled spans.
icons.md
]
(
./rules/icons.md
)
`
use
`
data-icon
`
.
**
`
data-icon="inline-start"
`
or
`
data-icon="inline-end"
`
on the icon.
`
size-4
`
or
`
w-4 h-4
`
.
`
icon={CheckIcon}
`
, not a string lookup.
`
npx shadcn@latest preset decode <code>
`
,
`
preset url <code>
`
, or
`
preset open <code>
`
. For project-aware preset detection, use
`
npx shadcn@latest preset resolve
`
.
`
npx shadcn@latest apply <code>
`
for existing projects, or
`
npx shadcn@latest init --preset <code>
`
when initializing.
"
email
"
>
Email
</
FieldLabel
>
"
email
"
/>
>
/>
>
"
inline-start
"
/>
"
>
// correct
"
>
// wrong
size-10
"
>
// correct
w-10 h-10
"
>
// wrong
secondary
"
>
+20.1%
</
Badge
>
// correct
"
>
+20.1%
</
span
>
// wrong
`
,
`
Combobox
`
,
`
Switch
`
,
`
Checkbox
`
,
`
RadioGroup
`
,
`
Textarea
`
,
`
InputOTP
`
,
`
Slider
`
|
`
|
`
,
`
Badge
`
,
`
Avatar
`
|
`
,
`
Breadcrumb
`
,
`
Tabs
`
,
`
Pagination
`
|
`
(side panel),
`
Drawer
`
(bottom sheet),
`
AlertDialog
`
(confirmation)
|
`
,
`
Progress
`
,
`
Skeleton
`
,
`
Spinner
`
|
`
|
`
,
`
Resizable
`
,
`
ScrollArea
`
,
`
Accordion
`
,
`
Collapsible
`
|
`
,
`
Menubar
`
|
`
,
`
Popover
`
|
**
→ use the actual alias prefix for imports (e.g.
`
@/
`
,
`
~/
`
), never hardcode.
**
→ when
`
true
`
, components using
`
useState
`
,
`
useEffect
`
, event handlers, or browser APIs need
`
"use client"
`
at the top of the file. Always reference this field when advising on the directive.
**
→
`
"v4"
`
uses
`
@theme inline
`
blocks;
`
"v3"
`
uses
`
tailwind.config.js
`
.
**
→ the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
**
→ component visual treatment (e.g.
`
nova
`
,
`
vega
`
).
**
→ primitive library (
`
radix
`
or
`
base
`
). Affects component APIs and available props.
**
→ determines icon imports. Use
`
lucide-react
`
for
`
lucide
`
,
`
@tabler/icons-react
`
for
`
tabler
`
, etc. Never assume
`
lucide-react
`
.
**
→ exact file-system destinations for components, utils, hooks, etc.
**
→ routing and file conventions (e.g. Next.js App Router vs Vite SPA).
**
→ use this for any non-shadcn dependency installs (e.g.
`
pnpm add date-fns
`
vs
`
npm install date-fns
`
).
**
→ resolved preset code and values for the current project. Use
`
npx shadcn@latest preset resolve --json
`
when you only need preset information.
`
command
]
(
./cli.md
)
for the full field reference.
dialog
select
`
and fetch the URLs first.
**
This ensures you're working with the correct API and usage patterns rather than guessing.
`
npx shadcn@latest info
`
again if you need to refresh.
`
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.
`
npx shadcn@latest search
`
.
`
npx shadcn@latest docs <component>
`
to get URLs, then fetch them. Use
`
npx shadcn@latest view
`
to browse registry items you haven't installed. To preview changes to installed components, use
`
npx shadcn@latest add --diff
`
.
`
npx shadcn@latest add
`
. When updating existing components, use
`
--dry-run
`
and
`
--diff
`
to preview changes first (see
[
Updating Components
]
(
#updating-components
)
below).
`
@bundui
`
,
`
@magicui
`
), 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@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.
**
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-react
`
but the project uses
`
hugeicons
`
, swap the imports and icon names accordingly). Fix all issues before moving on.
**
do not guess the registry
**
. If no registry is specified (e.g. user says "add a login block" without specifying
`
@shadcn
`
,
`
@tailark
`
, etc.), ask which registry to use. Never default to a registry on behalf of the user.
**
overwrite
**
,
**
partial
**
,
**
merge
**
, or
**
skip
**
?
:
`
npx shadcn@latest preset resolve
`
. Use
`
--json
`
when you need structured values.
:
`
npx shadcn@latest preset decode <code>
`
. Use
`
preset url <code>
`
or
`
preset open <code>
`
to share or open the preset builder.
:
`
npx shadcn@latest apply <code>
`
. Overwrites detected components, fonts, and CSS variables.
:
`
npx shadcn@latest apply <code> --only theme,font
`
. Updates only the selected preset parts without reinstalling UI components. Supported values are
`
theme
`
and
`
font
`
; comma-separated combinations are allowed.
`
icon
`
is intentionally not supported, because icon changes may require full component reinstall and transforms.