shadcn-ui
jezweb/claude-skills
Install and configure shadcn/ui components for themed React projects with dependency management and UI recipes.
What is shadcn-ui?
shadcn/ui adds pre-built, customizable React components to projects with Tailwind CSS theme infrastructure already in place. Use this skill when adding components, building forms, creating data tables, or setting up navigation after tailwind-theme-builder has configured the theme.
- Install foundation components (button, input, card) and feature components (forms, tables, dialogs, navigation) in correct dependency order
- Manage external dependencies (react-hook-form, zod, sonner, @tanstack/react-table) required by specific components
- Customize components with semantic CSS tokens from your theme instead of raw Tailwind colors
- Avoid common gotchas: Radix Select empty strings, React Hook Form null values, Lucide icon tree-shaking, Dialog width overrides
- Combine components into working UI patterns (forms, data tables, modals, navigation) using provided recipes
How to install shadcn-ui
npx skills add https://github.com/jezweb/claude-skills --skill shadcn-ui- Theme infrastructure must exist (CSS variables, components.json, cn() utility)
- tailwind-theme-builder skill should be run first to set up theme infrastructure
- pnpm or npm package manager installed
How to use shadcn-ui
- 1.Assess your project's UI needs (forms, tables, navigation, modals)
- 2.Install foundation components first: button, input, label, card
- 3.Install feature components based on identified needs using pnpm dlx shadcn@latest add [component]
- 4.Install required external dependencies (react-hook-form, zod, sonner, @tanstack/react-table) as needed
- 5.Customize components by editing variant definitions and using semantic tokens from your theme
- 6.Combine components into working patterns using provided recipes for forms, tables, modals, and navigation
Use cases
- Building forms with validation using Form + Input + Label + Button + Toast components
- Creating sortable, paginated data tables with Table + Badge + Pagination components
- Setting up admin CRUD interfaces with Dialog + Form + Table + Button + Toast
- Implementing responsive navigation with Sheet (mobile) + NavigationMenu (desktop) + ModeToggle
- Building settings/preferences pages with Tabs + Form + Switch + Select + Toast
- React developers building UI with Tailwind CSS and semantic theming
- Teams using shadcn/ui component library for consistent design systems
- Developers needing form validation, data tables, and modal dialogs
- Projects requiring accessible, customizable component patterns
shadcn-ui FAQ
Theme infrastructure must exist with CSS variables, components.json, and cn() utility. Run tailwind-theme-builder first if not already set up.
Radix Select doesn't accept empty strings. Use a sentinel value like '__any__' instead, then map it back to an empty string in your logic.
Don't spread {...field} directly into Input. Instead, manually assign value={field.value ?? ''}, onChange, onBlur, name, and ref to avoid null being passed.
Dynamic imports get tree-shaken. Use an explicit map of imported icons instead: import { Home, Users } from 'lucide-react' and create a Record mapping icon names to components.
Use semantic tokens from your theme (bg-primary, bg-card, text-card-foreground) instead of raw Tailwind colors. Edit component files to add custom variants if needed.
Full instructions (SKILL.md)
Source of truth, from jezweb/claude-skills.
name: shadcn-ui description: "Install and configure shadcn/ui components for React projects. Guides component selection, installation order, dependency management, customisation with semantic tokens, and common UI recipes (forms, data tables, navigation, modals). Use after tailwind-theme-builder has set up the theme infrastructure, when adding components, building forms, creating data tables, or setting up navigation." compatibility: claude-code-only
shadcn/ui Components
Add shadcn/ui components to a themed React project. This skill runs AFTER tailwind-theme-builder has set up CSS variables, ThemeProvider, and dark mode. It handles component installation, customisation, and combining components into working patterns.
Prerequisite: Theme infrastructure must exist (CSS variables, components.json, cn() utility). Use tailwind-theme-builder first if not set up.
Installation Order
Install components in dependency order. Foundation components first, then feature components:
Foundation (install first)
pnpm dlx shadcn@latest add button
pnpm dlx shadcn@latest add input label
pnpm dlx shadcn@latest add card
Feature Components (install as needed)
# Forms
pnpm dlx shadcn@latest add form # needs: react-hook-form, zod, @hookform/resolvers
pnpm dlx shadcn@latest add textarea select checkbox switch
# Feedback
pnpm dlx shadcn@latest add toast # needs: sonner
pnpm dlx shadcn@latest add alert badge
# Overlay
pnpm dlx shadcn@latest add dialog sheet popover dropdown-menu
# Data Display
pnpm dlx shadcn@latest add table # for data tables, also: @tanstack/react-table
pnpm dlx shadcn@latest add tabs separator avatar
# Navigation
pnpm dlx shadcn@latest add navigation-menu command
External Dependencies
| Component | Requires |
|---|---|
| Form | react-hook-form, zod, @hookform/resolvers |
| Toast | sonner |
| Data Table | @tanstack/react-table |
| Command | cmdk |
| Date Picker | date-fns (optional) |
Install external deps separately: pnpm add react-hook-form zod @hookform/resolvers
Known Gotchas
These are documented corrections that prevent common bugs:
Radix Select — No Empty Strings
// Don't use empty string values
<SelectItem value="">All</SelectItem> // BREAKS
// Use sentinel value
<SelectItem value="__any__">All</SelectItem> // WORKS
const actual = value === "__any__" ? "" : value
React Hook Form — Null Values
// Don't spread {...field} — it passes null which Input rejects
<Input
value={field.value ?? ''}
onChange={field.onChange}
onBlur={field.onBlur}
name={field.name}
ref={field.ref}
/>
Lucide Icons — Tree-Shaking
// Don't use dynamic import — icons get tree-shaken in production
import * as LucideIcons from 'lucide-react'
const Icon = LucideIcons[iconName] // BREAKS in prod
// Use explicit map
import { Home, Users, Settings, type LucideIcon } from 'lucide-react'
const ICON_MAP: Record<string, LucideIcon> = { Home, Users, Settings }
const Icon = ICON_MAP[iconName]
Dialog Width Override
// Default sm:max-w-lg won't be overridden by max-w-6xl
<DialogContent className="max-w-6xl"> // DOESN'T WORK
// Use same breakpoint prefix
<DialogContent className="sm:max-w-6xl"> // WORKS
Customising Components
shadcn components use semantic CSS tokens from your theme. To customise:
Variant extension
Add custom variants by editing the component file in src/components/ui/:
// button.tsx — add a "brand" variant
const buttonVariants = cva("...", {
variants: {
variant: {
default: "bg-primary text-primary-foreground",
brand: "bg-brand text-brand-foreground hover:bg-brand/90",
// ... existing variants
},
},
})
Colour overrides
Use semantic tokens from your theme — never raw Tailwind colours:
// Don't use raw colours
<Button className="bg-blue-500"> // WRONG
// Use semantic tokens
<Button className="bg-primary"> // RIGHT
<Card className="bg-card text-card-foreground"> // RIGHT
Workflow
Step 1: Assess Needs
Determine what UI patterns the project needs:
| Need | Components |
|---|---|
| Forms with validation | Form, Input, Label, Select, Textarea, Button, Toast |
| Data display with sorting | Table, Badge, Pagination |
| Admin CRUD interface | Dialog, Form, Table, Button, Toast |
| Marketing/landing page | Card, Button, Badge, Separator |
| Settings/preferences | Tabs, Form, Switch, Select, Toast |
| Navigation | NavigationMenu (desktop), Sheet (mobile), ModeToggle |
Step 2: Install Components
Install foundation first, then feature components for the identified needs. Use the commands above.
Step 3: Build Recipes
Combine components into working patterns. See references/recipes.md for complete working examples:
- Contact Form — Form + Input + Textarea + Button + Toast
- Data Table — Table + Column sorting + Pagination + Search
- Modal CRUD — Dialog + Form + Button
- Navigation — Sheet + NavigationMenu + ModeToggle
- Settings Page — Tabs + Form + Switch + Select + Toast
Step 4: Customise
Apply project-specific colours and variants using semantic tokens from the theme.
Reference Files
| When | Read |
|---|---|
| Choosing components, install commands, props | references/component-catalogue.md |
| Building complete UI patterns | references/recipes.md |
Related skills
More from jezweb/claude-skills and the wider catalog.
