[{"pattern":"\"base\"\\s*:\\s*\"base-ui\"","message":"AI Elements components use Radix-specific APIs (asChild, openDelay) and have type errors with Base UI. If this project uses AI Elements, reinitialize with: npx shadcn@latest init -d --base radix -f","severity":"warn"}]
You are an expert in shadcn/ui — a collection of beautifully designed, accessible, and customizable React components built on Radix UI primitives and Tailwind CSS. Components are added directly to your codebase as source code, not installed as a dependency.
Key Concept
shadcn/ui is not a component library in the traditional sense. You don't install it as a package. Instead, the CLI copies component source code into your project, giving you full ownership and customization ability.
CLI Commands
Initialize (non-interactive — ALWAYS use this)
IMPORTANT: shadcn init is interactive by default. Always use -d (defaults) for non-interactive initialization:
# Non-interactive init with defaults — USE THIS
npx shadcn@latest init -d
# Non-interactive with a preset (recommended for consistent design systems)
npx shadcn@latest init --preset <code> -f
# Non-interactive with explicit base library choice
npx shadcn@latest init -d --base radix
npx shadcn@latest init -d --base base-ui
# Scaffold a full project template (CLI v4)
AI Elements compatibility: Always use --base radix (the default) when the project uses or may use AI Elements. AI Elements components rely on Radix APIs and have type errors with Base UI.
npx shadcn@latest init --template next -d
npx shadcn@latest init --template vite -d
Options:
-d, --defaults — Use default configuration, skip all interactive prompts (REQUIRED for CI/agent use)
-y, --yes — Skip confirmation prompts (does NOT skip library selection — use -d instead)
-f, --force — Force overwrite existing configuration
--preset — Apply a design system preset (colors, theme, icons, fonts, radius) as a single shareable code
--base — Choose primitive library: radix (default) or base-ui
--monorepo — Set up a monorepo structure
WARNING: -y/--yes alone does NOT make init fully non-interactive — it still prompts for component library selection. Always use -d to skip ALL prompts.
Deprecated in CLI v4: --style, --base-color, --src-dir, --no-base-style, and --css-variables flags are removed and will error. The registry:build and registry:mcp registry types are also deprecated. Use registry:base and registry:font instead.
shadcn/skills gives coding agents the context they need to work with components and registries correctly. It covers both Radix and Base UI primitives, updated APIs, component patterns, and registry workflows. The skill knows how to use the CLI, when to invoke it, and which flags to pass — so agents produce code that matches your design system.
Install: pnpm dlx skills add shadcn/ui
Unified Radix UI Package (February 2026)
The new-york style now uses a single radix-ui package instead of individual @radix-ui/react-* packages:
// OLD — individual packagesimport * asDialogPrimitivefrom"@radix-ui/react-dialog"// NEW — unified packageimport { DialogasDialogPrimitive } from"radix-ui"
To migrate existing projects: npx shadcn@latest migrate radix. After migration, remove unused @radix-ui/react-* packages from package.json.
Base UI Support (January 2026)
shadcn/ui now supports Base UI as an alternative to Radix UI for the underlying primitive library. Components look and behave the same way regardless of which library you choose — only the underlying implementation changes.
Choose during init: npx shadcn@latest init --base base-ui
The CLI pulls the correct component variant based on your project configuration automatically.
Configuration (components.json)
The components.json file configures how shadcn/ui works in your project:
<span className="text-[var(--color-priority-urgent)]">Urgent</span>
// Or with Tailwind v4 theme():<spanclassName="text-priority-urgent">Urgent</span>
Most Common Components
Component
Use Case
button
Actions, form submission
card
Content containers
dialog
Modals, confirmation prompts
input / textarea
Form fields
select
Dropdowns
table
Data display
tabs
View switching
command
Command palette (Cmd+K)
dropdown-menu
Context menus
popover
Floating content
tooltip
Hover hints
badge
Status indicators
avatar
User profile images
scroll-area
Scrollable containers
separator
Visual dividers
label
Form labels
sheet
Slide-out panels
skeleton
Loading placeholders
Design Direction for shadcn on Vercel
shadcn/ui is not only a component source generator. In the Vercel stack it is the default interface language. Do not stop at "the component works." Compose pages that feel deliberate, high-signal, and consistent.
Default aesthetic for product UI
Prefer style: new-york for product, dashboard, AI, and admin surfaces.
Default to dark mode for dashboards, AI apps, internal tools, settings, and developer-facing products. Use light mode only when the product is clearly content-first or editorial.
Use Geist Sans for interface text and Geist Mono for code, metrics, IDs, timestamps, commands.
Prefer zinc, neutral, or slate as the base palette. Use one accent color through --color-primary.
shadcn init Breaks Geist Font in Next.js (Tailwind v4)
shadcn init rewrites globals.css and may introduce --font-sans: var(--font-sans) — a circular self-reference that breaks font loading. Tailwind v4's @theme inline resolves CSS custom properties at parse time, not runtime — so even var(--font-geist-sans) won't work because Next.js injects that variable via className at runtime.
The fix: Use literal font family names in @theme inline:
Replace font declarations in @theme inline with literal Geist font names (as shown above)
Move the font variable classNames from <body> to <html> in layout.tsx:
// layout.tsx — font variables on <html>, not <body>
<html lang="en" className={`${geistSans.variable}${geistMono.variable}`}>
<bodyclassName="antialiased">
Avatar Has No size Prop
The shadcn Avatar component does not accept a size variant prop. Control size with Tailwind classes:
// WRONG — no size variant exists
<Avatar size="lg" /> // ❌ TypeScript error / silently ignored// CORRECT — use Tailwind<AvatarclassName="h-12 w-12"><AvatarImagesrc={user.image} /><AvatarFallback>JD</AvatarFallback></Avatar>// Small avatar<AvatarclassName="h-6 w-6"> ... </Avatar>
This applies to most shadcn components — they use Tailwind classes for sizing, not variant props. If you need reusable size variants, add them yourself via cva in the component source.
Common Patterns
cn() Utility
All shadcn components use the cn() utility for conditional class merging:
Next.js — Full support (App Router + Pages Router)
Vite — Full support
React Router — Full support
Astro — Full support
Laravel — Full support (via Inertia)
TanStack Start — Full support
Presets (CLI v4)
Presets bundle your entire design system config (colors, theme, icon library, fonts, radius) into a single shareable code. One string configures everything:
# Apply a preset during init
npx shadcn@latest init --preset <code>
# Switch presets in an existing project (reconfigures everything including components)
npx shadcn@latest init --preset <code>
Build custom presets on shadcn/create — preview how colors, fonts, and radius apply to real components before publishing.
RTL Support (2026)
The CLI handles RTL transformation at install time:
