shadcn-components

What this skill does

# shadcn/ui Component Usage

Guide for using, customizing, and composing shadcn/ui components in React applications.

## Adding Components

### CLI Installation

```bash
# Add single component
npx shadcn@latest add button

# Add multiple components
npx shadcn@latest add button card dialog input

# Add with dependencies
npx shadcn@latest add form  # Adds form + label + input
```

### Manual Installation

Components can be copied directly from https://ui.shadcn.com/docs/components

## Component Categories

### Form Components

| Component | Use Case |
|-----------|----------|
| `input` | Text input fields |
| `textarea` | Multi-line text |
| `select` | Dropdown selection |
| `checkbox` | Boolean toggle |
| `radio-group` | Single selection from options |
| `switch` | On/off toggle |
| `slider` | Range selection |
| `form` | Form validation wrapper |

### Layout Components

| Component | Use Case |
|-----------|----------|
| `card` | Content container |
| `separator` | Visual divider |
| `aspect-ratio` | Fixed aspect container |
| `scroll-area` | Custom scrollbars |
| `resizable` | Resizable panels |

### Feedback Components

| Component | Use Case |
|-----------|----------|
| `alert` | Important messages |
| `badge` | Status indicators |
| `progress` | Loading progress |
| `skeleton` | Loading placeholders |
| `toast/sonner` | Notifications |

### Overlay Components

| Component | Use Case |
|-----------|----------|
| `dialog` | Modal windows |
| `alert-dialog` | Confirmation dialogs |
| `sheet` | Side panels |
| `drawer` | Bottom/side drawers |
| `popover` | Floating content |
| `tooltip` | Hover information |
| `hover-card` | Rich hover content |

### Navigation Components

| Component | Use Case |
|-----------|----------|
| `tabs` | Tabbed interfaces |
| `navigation-menu` | Main navigation |
| `breadcrumb` | Location breadcrumbs |
| `pagination` | Page navigation |
| `command` | Command palette |
| `menubar` | Application menu |
| `context-menu` | Right-click menu |
| `dropdown-menu` | Action menus |

### Data Display

| Component | Use Case |
|-----------|----------|
| `table` | Data tables |
| `data-table` | Advanced tables (TanStack) |
| `accordion` | Collapsible sections |
| `collapsible` | Single collapse |
| `avatar` | User images |
| `calendar` | Date picker |
| `carousel` | Image galleries |

## Component Variants

Most components support variants via `variant` prop:

### Button Variants

```tsx
<Button variant="default">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>
```

### Button Sizes

```tsx
<Button size="default">Default</Button>
<Button size="sm">Small</Button>
<Button size="lg">Large</Button>
<Button size="icon">Icon Only</Button>
```

### Badge Variants

```tsx
<Badge variant="default">Default</Badge>
<Badge variant="secondary">Secondary</Badge>
<Badge variant="destructive">Destructive</Badge>
<Badge variant="outline">Outline</Badge>
```

## Component Customization

### Using cn() for Custom Classes

```tsx
import { cn } from "@/lib/utils"

<Button className={cn(
  "w-full",
  isActive && "ring-2 ring-primary",
  disabled && "opacity-50"
)}>
  Custom Button
</Button>
```

### Extending Components

Create wrapper components for reusable customizations:

```tsx
// components/ui/button-loading.tsx
import { Button, ButtonProps } from "@/components/ui/button"
import { Loader2 } from "lucide-react"

interface ButtonLoadingProps extends ButtonProps {
  loading?: boolean
}

export function ButtonLoading({
  loading,
  children,
  disabled,
  ...props
}: ButtonLoadingProps) {
  return (
    <Button disabled={loading || disabled} {...props}>
      {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
      {children}
    </Button>
  )
}
```

### Adding New Variants

Edit the component's cva() definition:

```tsx
// components/ui/button.tsx
const buttonVariants = cva(
  "...", // base styles
  {
    variants: {
      variant: {
        // existing variants...
        success: "bg-green-500 text-white hover:bg-green-600",
      },
    },
  }
)
```

## Common Patterns

### Dialog with Form

```tsx
<Dialog>
  <DialogTrigger asChild>
    <Button>Edit Profile</Button>
  </DialogTrigger>
  <DialogContent className="sm:max-w-[425px]">
    <DialogHeader>
      <DialogTitle>Edit Profile</DialogTitle>
      <DialogDescription>
        Make changes to your profile here.
      </DialogDescription>
    </DialogHeader>
    <form onSubmit={handleSubmit}>
      <div className="grid gap-4 py-4">
        <div className="grid gap-2">
          <Label htmlFor="name">Name</Label>
          <Input id="name" defaultValue="John Doe" />
        </div>
      </div>
      <DialogFooter>
        <Button type="submit">Save changes</Button>
      </DialogFooter>
    </form>
  </DialogContent>
</Dialog>
```

### Dropdown Menu with Icons

```tsx
import {
  User, Settings, LogOut, Plus
} from "lucide-react"

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="ghost">Menu</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end">
    <DropdownMenuLabel>My Account</DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuItem>
      <User className="mr-2 h-4 w-4" />
      Profile
    </DropdownMenuItem>
    <DropdownMenuItem>
      <Settings className="mr-2 h-4 w-4" />
      Settings
    </DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem className="text-destructive">
      <LogOut className="mr-2 h-4 w-4" />
      Log out
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

### Tabs with Content

```tsx
<Tabs defaultValue="account" className="w-full">
  <TabsList className="grid w-full grid-cols-2">
    <TabsTrigger value="account">Account</TabsTrigger>
    <TabsTrigger value="password">Password</TabsTrigger>
  </TabsList>
  <TabsContent value="account">
    <Card>
      <CardHeader>
        <CardTitle>Account</CardTitle>
        <CardDescription>
          Make changes to your account here.
        </CardDescription>
      </CardHeader>
      <CardContent>
        {/* Account form */}
      </CardContent>
    </Card>
  </TabsContent>
  <TabsContent value="password">
    <Card>
      <CardHeader>
        <CardTitle>Password</CardTitle>
      </CardHeader>
      <CardContent>
        {/* Password form */}
      </CardContent>
    </Card>
  </TabsContent>
</Tabs>
```

## Reference Files

- **`references/component-catalog.md`** - Full component list with props
- **`references/icon-patterns.md`** - Lucide icon usage patterns

## Resources

- Component docs: https://ui.shadcn.com/docs/components
- Examples: https://ui.shadcn.com/examples
- Blocks: https://ui.shadcn.com/blocks