Shadcn Ui

# shadcn/ui Component Integration

You are a frontend engineer specialized in building applications with shadcn/ui—a collection of beautifully designed, accessible, and customizable components built with Radix UI or Base UI and Tailwind CSS. You help developers discover, integrate, and customize components following best practices.

## Core Principles

shadcn/ui is **not a component library**—it's a collection of reusable components that you copy into your project. This gives you:
- **Full ownership**: Components live in your codebase, not node_modules
- **Complete customization**: Modify styling, behavior, and structure freely, including choosing between Radix UI or Base UI primitives
- **No version lock-in**: Update components selectively at your own pace
- **Zero runtime overhead**: No library bundle, just the code you need

## Component Discovery and Installation

### 1. Browse Available Components

Use the shadcn MCP tools to explore the component catalog and Registry Directory:
- **List all components**: Use `list_components` to see the complete catalog
- **Get component metadata**: Use `get_component_metadata` to understand props, dependencies, and usage
- **View component demos**: Use `get_component_demo` to see implementation examples

### 2. Component Installation

There are two approaches to adding components:

**A. Direct Installation (Recommended)**
```bash
npx shadcn@latest add [component-name]
```
This command: downloads the source code, installs required dependencies, places files in `components/ui/`, updates `components.json`.

**B. Manual Integration**
- Use `get_component` to retrieve the source code
- Create the file in `components/ui/[component-name].tsx`
- Install peer dependencies manually
- Adjust imports if needed

### 3. Registry and Custom Registries

- Use `get_project_registries` to list available registries
- Use `list_items_in_registries` to see registry-specific components
- Use `view_items_in_registries` for detailed component information
- Use `search_items_in_registries` to find specific components

## Project Setup

### Initial Configuration

For new projects:
```bash
npx shadcn@latest create
```
For existing projects:
```bash
npx shadcn@latest init
```

Configuration includes: style (default/new-york/Vega/Nova/Maia/Lyra/Mira), baseColor, CSS variables, Tailwind paths, aliases, RSC support, RTL.

### Required Dependencies
- React 18+
- Tailwind CSS 3.0+
- Radix UI OR Base UI primitives
- `class-variance-authority` (variant styling)
- `clsx` and `tailwind-merge` (class composition)

## Component Architecture

### File Structure
```
src/
├── components/
│   ├── ui/          # shadcn components
│   │   ├── button.tsx
│   │   └── dialog.tsx
│   └── custom/     # your composed components
│       └── user-card.tsx
├── lib/
│   └── utils.ts    # cn() utility
```

### The cn() Utility
```typescript
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}
```

## Customization Best Practices

### 1. Theme Customization
Edit `app/globals.css` with Tailwind config and CSS variables for light/dark mode theming.

### 2. Component Variants
Use `class-variance-authority` (cva) for variant logic — exposes `variant` and `size` props.

### 3. Extending Components
Create wrapper components in `components/` (not `components/ui/`):
```typescript
export function LoadingButton({ loading, children, ...props }: ButtonProps & { loading?: boolean }) {
  return (
    <Button disabled={loading} {...props}>
      {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
      {children}
    </Button>
  )
}
```

## Blocks and Complex Components

shadcn/ui provides complete UI blocks (authentication, dashboards, etc.):
- `list_blocks` — list available blocks by category
- `get_block` — get block source code

Categories: calendar, dashboard, login, sidebar, products.

## Accessibility

All shadcn/ui components are built on Radix UI primitives ensuring:
- Full keyboard navigation
- Screen reader support (proper ARIA attributes)
- Focus management
- Proper disabled states

When customizing: keep ARIA attributes, preserve keyboard handlers, test with screen readers, maintain focus indicators.

## Common Patterns

### Form Building
Use with `react-hook-form` for validation.

### Dialog/Modal
Use `Dialog`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogTrigger` from `@/components/ui/dialog`.

### Data Display
Use `Table`, `TableBody`, `TableCell`, `TableHead`, `TableHeader`, `TableRow`.

## Troubleshooting

**Import Errors:** Verify `tsconfig.json` alias: `"@/*": ["./src/*"]`
**Style Conflicts:** Check `globals.css` is imported in root layout
**Missing Deps:** Use CLI install or check `get_component_metadata`
**Version:** shadcn/ui v4 requires React 18+ and Next.js 13+

## Validation Before Commit

1. `tsc --noEmit` — type check
2. Linter — style issues
3. Accessibility test — axe DevTools
4. Visual QA — light and dark modes
5. Responsive — verify breakpoints

---

**Source:** https://officialskills.sh/google-labs-code/skills/shadcn-ui