Shadcn Ui

shadcn/ui Component Guide

Build accessible, customisable UI components with shadcn/ui, Radix UI, and Tailwind CSS.

When to Use

• Setting up a new project with shadcn/ui
• Installing or configuring components
• Building forms with React Hook Form and Zod
• Creating accessible UI (buttons, dialogs, dropdowns, sheets)
• Customising themes with Tailwind CSS variables
• Implementing design systems

MCP Tools (Preferred Workflow)

Use the shadcn MCP tools as the primary method for component discovery and installation. Fall back to CLI commands only when MCP tools are unavailable.

Discovery Workflow

1. Check project registries: Call mcp__shadcn__get_project_registries to verify components.json exists
2. Search for components: Call mcp__shadcn__search_items_in_registries with the registry and query
3. View component details: Call mcp__shadcn__view_items_in_registries to see source code and dependencies
4. Get usage examples: Call mcp__shadcn__get_item_examples_from_registries for implementation patterns
5. Get install command: Call mcp__shadcn__get_add_command_for_items for the exact CLI command

MCP Tool Reference

| Tool | Purpose | |------|---------| | get_project_registries | Check configured registries from components.json | | search_items_in_registries | Fuzzy search for components by name/description | | list_items_in_registries | List all available components in a registry | | view_items_in_registries | View source code, types, and dependencies | | get_item_examples_from_registries | Get usage examples for components | | get_add_command_for_items | Get the CLI install command for components | | get_audit_checklist | Get accessibility and quality audit checklist |

Finding and installing a component via MCP

1. Search: search_items_in_registries(registries: ["@shadcn"], query: "date picker")
2. View: view_items_in_registries(items: ["@shadcn/date-picker"])
3. Examples: get_item_examples_from_registries(items: ["@shadcn/date-picker"])
4. Install: get_add_command_for_items(items: ["@shadcn/date-picker"])

CLI Commands

Quick Start

New project:

npx create-next-app@latest my-app --typescript --tailwind --eslint --app
cd my-app
npx shadcn@latest init
npx shadcn@latest add button input form card dialog select

Existing project:

npx shadcn@latest init

CLI Reference

| Command | Purpose | |---------|---------| | npx shadcn@latest init | Initialise shadcn/ui in a project | | npx shadcn@latest add | Add a component | | npx shadcn@latest add --all | Add all components | | npx shadcn@latest search | Search registries | | npx shadcn@latest list | List available components | | npx shadcn@latest view | View a component before installing | | npx shadcn@latest build | Generate registry JSON files | | npx shadcn@latest migrate | Run project migrations |

See references/cli-reference.md for framework-specific installation and registry configuration.

Setup Verification Checklist

After initialisation, verify the setup works:

Setup Verification:
- [ ] `components.json` exists in project root
- [ ] `@/components/ui/` directory created
- [ ] `@/lib/utils.ts` contains the `cn` function
- [ ] `globals.css` has CSS variables for theming
- [ ] `tailwind.config` includes shadcn colour tokens
- [ ] Test: `npx shadcn@latest add button` installs without errors
- [ ] Test: Import and render `` compiles without errors

Component Quick Reference

| Component | Install | Key Props | |-----------|---------|-----------| | Button | add button | variant, size, asChild | | Input | add input | type, placeholder, disabled | | Form | add form | React Hook Form + Zod integration | | Card | add card | CardHeader, CardContent, CardFooter | | Dialog | add dialog | DialogTrigger, DialogContent | | Select | add select | SelectTrigger, SelectContent, SelectItem | | Sheet | add sheet | side="left\|right\|top\|bottom" | | Toast | add toast | useToast() hook, variant | | Table | add table | TableHeader, TableBody, TableRow |

Install all: npx shadcn@latest add --all

Core Patterns

Button Variants

import { Button } from "@/components/ui/button"

// Variants: default, destructive, outline, secondary, ghost, link
Delete

// Sizes: default, sm, lg, icon

// Loading state

  
  Loading

Form with Validation

"use client"

import { zodResolver } from "@hookform/resolvers/zod"
import { useForm } from "react-hook-form"
import * as z from "zod"
import { Button } from "@/components/ui/button"
import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form"
import { Input } from "@/components/ui/input"

const formSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
})

export function LoginForm() {
  const form = useForm>({
    resolver: zodResolver(formSchema),
    defaultValues: { email: "", password: "" },
  })

  return (
    
      
         (
          
            Email
            
            
          
        )} />
         (
          
            Password
            
            
          
        )} />
        Login
      
    
  )
}

Dialog (Modal)

import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"

  
    Open
  
  
    
      Edit profile
      Make changes here.
    
    {/* Content */}
    
      Save
    
  

Toast Notifications

Add ` to the root layout once (see references/nextjs-integration.md), then call useToast` anywhere:

import { useToast } from "@/components/ui/use-toast"

const { toast } = useToast()
toast({ title: "Success", description: "Changes saved." })
toast({ variant: "destructive", title: "Error", description: "Something went wrong." })

Theming

Customise via CSS variables in globals.css:

:root {
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  --radius: 0.5rem;
}
.dark {
  --primary: 210 40% 98%;
  --primary-foreground: 222.2 47.4% 11.2%;
}

See references/configuration.md for complete config files (TSConfig, Tailwind, CSS variables, dependencies).

Best Practices

1. Verify accessibility: Run get_audit_checklist after adding components. Check keyboard navigation and screen reader output.
2. Validate with Zod: Define a Zod schema for every form. Pass it to zodResolver in useForm.
3. Use cn() for all class merging: Never concatenate class strings manually. cn() resolves Tailwind conflicts.
4. Keep server components default: Only add "use client" when the component uses hooks, event handlers, or browser APIs. See references/nextjs-integration.md.
5. Theme with CSS variables: Change colours in globals.css :root and .dark blocks. Do not hardcode colour values in components.

Error handling in form submission

async function onSubmit(values: z.infer) {
  try {
    const res = await fetch("/api/submit", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(values),
    })
    if (!res.ok) {
      const data = await res.json()
      toast({ variant: "destructive", title: "Submission failed", description: data.message ?? "Check your input and try again." })
      return
    }
    toast({ title: "Saved", description: "Your changes have been saved." })
    form.reset()
  } catch {
    toast({ variant: "destructive", title: "Network error", description: "Could not reach the server. Try again later." })
  }
}

Theming with CSS variables (brand recolour)

To change the primary brand colour across every component, edit only globals.css. Components pick up the change automatically because they reference hsl(var(--primary)).

/* globals.css */
:root {
  --primary: 262 83% 58%;          /* Violet brand */
  --primary-foreground: 210 40% 98%;
  --ring: 262 83% 58%;             /* Focus ring matches brand */
  --radius: 0.75rem;
}

.dark {
  --primary: 263 70% 65%;          /* Lighter violet for dark mode */
  --primary-foreground: 222 47% 11%;
  --ring: 263 70% 65%;
}

Do not hardcode bg-violet-600 in components -- it breaks dark mode and theme switches.

Post-install accessibility audit via MCP

After adding an interactive component, run the audit checklist before shipping.

1. Install: mcp__shadcn__get_add_command_for_items(items: ["@shadcn/dialog"]) then run the returned command
2. Audit: mcp__shadcn__get_audit_checklist() returns the keyboard and ARIA checks
3. Verify each item: focus trap works, Escape closes, DialogTitle is announced, trigger returns focus on close
4. If any check fails, inspect the installed file in @/components/ui/dialog.tsx and compare against the registry source via view_items_in_registries

References

All detailed documentation is in references/:

| File | Content | |------|---------| | configuration.md | TSConfig, Tailwind config, CSS variables, dependencies | | nextjs-integration.md | App Router, Server Components, API routes | | advanced-patterns.md | Complex forms, custom variants, dialog with forms, sheet nav | | cli-reference.md | All CLI commands, framework installs, registries | | extended-components.md | Terminal, Dock, Credit Card, QR Code, charts, animations, hooks | | learning-guide.md | Learning path, exercises, CVA and cn patterns |

External Links:

• Official Docs: https://ui.shadcn.com
• Radix UI: https://www.radix-ui.com
• React Hook Form: https://react-hook-form.com
• Zod: https://zod.dev

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: costa-marcello
• Source: costa-marcello/skillkit
• License: MIT

Install and usage instructions live in the source repository linked above.