shadcn-ui

What this skill does

# shadcn/ui Component Library

> shadcn/ui is a collection of beautifully-designed, accessible components and a code distribution platform. It is built with TypeScript, Tailwind CSS, and Radix UI primitives. It supports multiple frameworks including Next.js, Vite, Remix, Astro, and more. Open Source. Open Code. AI-Ready. It also comes with a command-line tool to install and manage components and a registry system to publish and distribute code.

## Key Principles

- **Open Code**: Components are copied into your project, not installed as dependencies
- **Composition**: Build complex UIs by composing simple components
- **Distribution**: CLI and registry system for easy component management
- **Beautiful Defaults**: Production-ready styling out of the box
- **AI-Ready**: Designed to work well with AI assistants

## Quick Reference

### CLI Commands

```bash
# Initialize shadcn/ui in your project
npx shadcn@latest init

# Add a component
npx shadcn@latest add button

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

# Add all components
npx shadcn@latest add --all

# Update components
npx shadcn@latest diff

# List available components
npx shadcn@latest add
```

### Configuration (components.json)

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/index.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}
```

---

## Documentation Index

### Overview

| Topic | URL | Description |
|-------|-----|-------------|
| Introduction | https://ui.shadcn.com/docs | Core principles and getting started |
| CLI | https://ui.shadcn.com/docs/cli | Command-line tool reference |
| components.json | https://ui.shadcn.com/docs/components-json | Configuration file documentation |
| Theming | https://ui.shadcn.com/docs/theming | Colors, typography, design tokens |
| Changelog | https://ui.shadcn.com/docs/changelog | Release notes and version history |
| About | https://ui.shadcn.com/docs/about | Credits and project information |

### Installation by Framework

| Framework | URL | Notes |
|-----------|-----|-------|
| **Vite** | https://ui.shadcn.com/docs/installation/vite | Recommended for this plugin |
| **TanStack Router** | https://ui.shadcn.com/docs/installation/tanstack-router | Works with TanStack ecosystem |
| TanStack Start | https://ui.shadcn.com/docs/installation/tanstack | Full-stack TanStack framework |
| Next.js | https://ui.shadcn.com/docs/installation/next | App Router and Pages Router |
| Remix | https://ui.shadcn.com/docs/installation/remix | Remix framework |
| Astro | https://ui.shadcn.com/docs/installation/astro | Astro framework |
| React Router | https://ui.shadcn.com/docs/installation/react-router | React Router v7+ |
| Laravel | https://ui.shadcn.com/docs/installation/laravel | Laravel Inertia |
| Gatsby | https://ui.shadcn.com/docs/installation/gatsby | Gatsby framework |
| Manual | https://ui.shadcn.com/docs/installation/manual | Without CLI |

---

## Installation Instructions

### TanStack Router (Recommended)

The fastest way to get started with shadcn/ui and TanStack Router:

```bash
# Create new project with shadcn/ui pre-configured
npx create-tsrouter-app@latest my-app --template file-router --tailwind --add-ons shadcn
```

Then add components:

```bash
npx shadcn@latest add button
```

Usage in routes:

```tsx
// src/routes/index.tsx
import { createFileRoute } from "@tanstack/react-router"
import { Button } from "@/components/ui/button"

export const Route = createFileRoute("/")({
  component: App,
})

function App() {
  return (
    <div>
      <Button>Click me</Button>
    </div>
  )
}
```

### Vite Installation

**Step 1: Create project**

```bash
npm create vite@latest
# Select: React + TypeScript
```

**Step 2: Add Tailwind CSS**

```bash
npm install tailwindcss @tailwindcss/vite
```

Replace `src/index.css`:

```css
@import "tailwindcss";
```

**Step 3: Configure TypeScript paths**

Edit `tsconfig.json`:

```json
{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

Edit `tsconfig.app.json`:

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

**Step 4: Configure Vite**

```bash
npm install -D @types/node
```

Edit `vite.config.ts`:

```typescript
import path from "path"
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
})
```

**Step 5: Initialize shadcn/ui**

```bash
npx shadcn@latest init
# Select: Neutral as base color
```

**Step 6: Add components**

```bash
npx shadcn@latest add button
```

Usage:

```tsx
// src/App.tsx
import { Button } from "@/components/ui/button"

function App() {
  return (
    <div className="flex min-h-svh flex-col items-center justify-center">
      <Button>Click me</Button>
    </div>
  )
}

export default App
```

### Manual Installation (Without CLI)

**Step 1: Add Tailwind CSS**

Follow the [Tailwind CSS installation guide](https://tailwindcss.com/docs/installation).

**Step 2: Add dependencies**

```bash
npm install class-variance-authority clsx tailwind-merge lucide-react tw-animate-css
```

**Step 3: Configure path aliases**

In `tsconfig.json`:

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}
```

**Step 4: Configure styles**

Create `src/styles/globals.css`:

```css
@import "tailwindcss";
@import "tw-animate-css";

@custom-variant dark (&:is(.dark *));

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --chart-1: oklch(0.646 0.222 41.116);
  --chart-2: oklch(0.6 0.118 184.704);
  --chart-3: oklch(0.398 0.07 227.392);
  --chart-4: oklch(0.828 0.189 84.429);
  --chart-5: oklch(0.769 0.188 70.08);
  --radius: 0.625rem;
  --sidebar: oklch(0.985 0 0);
  --sidebar-foreground: oklch(0.145 0 0);
  --sidebar-primary: oklch(0.205 0 0);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.97 0 0);
  --sidebar-accent-foreground: oklch(0.205 0 0);
  --sidebar-border: oklch(0.922 0 0);
  --sidebar-ring: oklch(0.708 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.145 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.145 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.396 0.141 25.723);
  --destructive-foreground: oklch(0.637 0.237 25.331);
  --border: oklch(0.269 0 0);
  --input: oklch(0.269 0 0);
  --ring: oklch(0.439 0 0);
  --chart-1: oklch(0.488 0.243 264.376);
  --chart-2: oklch(0.696