Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,370 @@
|
||||
# shadcn/ui Component Reference
|
||||
|
||||
## Overview
|
||||
|
||||
shadcn/ui provides a collection of re-usable components built with Radix UI and Tailwind CSS. Components are NOT installed as dependencies but copied into your project, giving you full control.
|
||||
|
||||
## Installation Command
|
||||
|
||||
```bash
|
||||
npx shadcn-ui@latest add [component-name]
|
||||
```
|
||||
|
||||
## Baseline Components for This Skill
|
||||
|
||||
The following components are installed by default:
|
||||
|
||||
### Core UI Elements
|
||||
- **button**: Primary interactive element with variants
|
||||
- **card**: Container for grouped content
|
||||
- **input**: Text input field
|
||||
- **label**: Form label with accessibility support
|
||||
- **dialog**: Modal dialog/overlay
|
||||
- **separator**: Visual or semantic separator
|
||||
|
||||
### Layout & Navigation
|
||||
- **sheet**: Slide-over panel (mobile sidebar)
|
||||
- **dropdown-menu**: Contextual menu with submenus
|
||||
- **navigation-menu**: Main navigation component
|
||||
|
||||
### Feedback & Notifications
|
||||
- **toast**: Temporary notifications (via Sonner)
|
||||
- **alert**: Static notification messages
|
||||
- **badge**: Status or category indicator
|
||||
|
||||
## Available Components by Category
|
||||
|
||||
### Form Components
|
||||
- `checkbox` - Checkbox input with label
|
||||
- `input` - Text input field
|
||||
- `label` - Form label
|
||||
- `textarea` - Multi-line text input
|
||||
- `select` - Dropdown select
|
||||
- `radio-group` - Radio button group
|
||||
- `switch` - Toggle switch
|
||||
- `slider` - Range slider
|
||||
- `form` - Form wrapper with React Hook Form integration
|
||||
- `combobox` - Searchable select (autocomplete)
|
||||
- `date-picker` - Date selection with calendar
|
||||
- `calendar` - Calendar component
|
||||
|
||||
### Layout Components
|
||||
- `card` - Content card with header/footer
|
||||
- `sheet` - Slide-over panel
|
||||
- `dialog` - Modal dialog
|
||||
- `popover` - Floating popover
|
||||
- `drawer` - Bottom drawer (mobile)
|
||||
- `separator` - Divider line
|
||||
- `scroll-area` - Custom scrollable area
|
||||
- `aspect-ratio` - Maintain aspect ratio
|
||||
- `resizable` - Resizable panels
|
||||
|
||||
### Navigation Components
|
||||
- `navigation-menu` - Main navigation
|
||||
- `menubar` - Desktop menu bar
|
||||
- `dropdown-menu` - Context/dropdown menu
|
||||
- `context-menu` - Right-click context menu
|
||||
- `tabs` - Tab navigation
|
||||
- `breadcrumb` - Breadcrumb navigation
|
||||
- `pagination` - Page navigation
|
||||
- `command` - Command palette (⌘K)
|
||||
|
||||
### Feedback Components
|
||||
- `toast` - Toast notifications
|
||||
- `alert` - Alert messages
|
||||
- `alert-dialog` - Confirmation dialog
|
||||
- `badge` - Status badge
|
||||
- `progress` - Progress indicator
|
||||
- `skeleton` - Loading skeleton
|
||||
- `spinner` - Loading spinner
|
||||
|
||||
### Data Display
|
||||
- `table` - Data table
|
||||
- `avatar` - User avatar
|
||||
- `tooltip` - Hover tooltip
|
||||
- `accordion` - Collapsible sections
|
||||
- `collapsible` - Simple collapsible
|
||||
- `hover-card` - Rich hover card
|
||||
- `data-table` - Advanced data table with sorting/filtering
|
||||
|
||||
### Utility Components
|
||||
- `toggle` - Toggle button
|
||||
- `toggle-group` - Toggle button group
|
||||
- `sonner` - Toast notification library integration
|
||||
- `carousel` - Image/content carousel
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Adding a Single Component
|
||||
|
||||
```bash
|
||||
npx shadcn-ui add button
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `components/ui/button.tsx`
|
||||
- Updates `components.json` if needed
|
||||
|
||||
### Adding Multiple Components
|
||||
|
||||
```bash
|
||||
npx shadcn-ui add button card input label
|
||||
```
|
||||
|
||||
### Using a Component
|
||||
|
||||
```tsx
|
||||
import { Button } from "@/components/ui/button"
|
||||
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
|
||||
|
||||
export default function Example() {
|
||||
return (
|
||||
<Card>
|
||||
<CardHeader>
|
||||
<CardTitle>Example Card</CardTitle>
|
||||
</CardHeader>
|
||||
<CardContent>
|
||||
<Button>Click me</Button>
|
||||
</CardContent>
|
||||
</Card>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Component Composition Patterns
|
||||
|
||||
### Form with Validation
|
||||
|
||||
```tsx
|
||||
import { useForm } from "react-hook-form"
|
||||
import { zodResolver } from "@hookform/resolvers/zod"
|
||||
import * as z from "zod"
|
||||
import { Button } from "@/components/ui/button"
|
||||
import { Input } from "@/components/ui/input"
|
||||
import { Label } from "@/components/ui/label"
|
||||
import { toast } from "sonner"
|
||||
|
||||
const schema = z.object({
|
||||
email: z.string().email(),
|
||||
password: z.string().min(8)
|
||||
})
|
||||
|
||||
export function LoginForm() {
|
||||
const form = useForm({
|
||||
resolver: zodResolver(schema)
|
||||
})
|
||||
|
||||
const onSubmit = (data) => {
|
||||
toast.success("Login successful!")
|
||||
}
|
||||
|
||||
return (
|
||||
<form onSubmit={form.handleSubmit(onSubmit)}>
|
||||
<div>
|
||||
<Label htmlFor="email">Email</Label>
|
||||
<Input id="email" {...form.register("email")} />
|
||||
</div>
|
||||
<Button type="submit">Login</Button>
|
||||
</form>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Dialog with Form
|
||||
|
||||
```tsx
|
||||
import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"
|
||||
import { Button } from "@/components/ui/button"
|
||||
import { Input } from "@/components/ui/input"
|
||||
|
||||
export function CreateDialog() {
|
||||
return (
|
||||
<Dialog>
|
||||
<DialogTrigger asChild>
|
||||
<Button>Create New</Button>
|
||||
</DialogTrigger>
|
||||
<DialogContent>
|
||||
<DialogHeader>
|
||||
<DialogTitle>Create Item</DialogTitle>
|
||||
</DialogHeader>
|
||||
<form>
|
||||
<Input placeholder="Item name" />
|
||||
<Button type="submit">Create</Button>
|
||||
</form>
|
||||
</DialogContent>
|
||||
</Dialog>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Navigation with Dropdown
|
||||
|
||||
```tsx
|
||||
import { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuLink } from "@/components/ui/navigation-menu"
|
||||
import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from "@/components/ui/dropdown-menu"
|
||||
import { Button } from "@/components/ui/button"
|
||||
|
||||
export function AppNav() {
|
||||
return (
|
||||
<NavigationMenu>
|
||||
<NavigationMenuList>
|
||||
<NavigationMenuItem>
|
||||
<NavigationMenuLink href="/">Home</NavigationMenuLink>
|
||||
</NavigationMenuItem>
|
||||
<NavigationMenuItem>
|
||||
<DropdownMenu>
|
||||
<DropdownMenuTrigger asChild>
|
||||
<Button variant="ghost">Products</Button>
|
||||
</DropdownMenuTrigger>
|
||||
<DropdownMenuContent>
|
||||
<DropdownMenuItem>Product A</DropdownMenuItem>
|
||||
<DropdownMenuItem>Product B</DropdownMenuItem>
|
||||
</DropdownMenuContent>
|
||||
</DropdownMenu>
|
||||
</NavigationMenuItem>
|
||||
</NavigationMenuList>
|
||||
</NavigationMenu>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Modifying Component Styles
|
||||
|
||||
Components use Tailwind classes and can be customized:
|
||||
|
||||
```tsx
|
||||
// Customize colors via CSS variables in globals.css
|
||||
:root {
|
||||
--primary: 200 100% 50%; /* Change primary color */
|
||||
}
|
||||
|
||||
// Or override with props
|
||||
<Button className="bg-purple-600 hover:bg-purple-700">
|
||||
Custom Color
|
||||
</Button>
|
||||
```
|
||||
|
||||
### Creating Variants
|
||||
|
||||
Use `class-variance-authority` (CVA) for variants:
|
||||
|
||||
```tsx
|
||||
import { cva } from "class-variance-authority"
|
||||
|
||||
const alertVariants = cva(
|
||||
"rounded-lg border p-4",
|
||||
{
|
||||
variants: {
|
||||
variant: {
|
||||
default: "bg-background text-foreground",
|
||||
destructive: "bg-destructive text-destructive-foreground",
|
||||
success: "bg-green-50 text-green-900"
|
||||
}
|
||||
},
|
||||
defaultVariants: {
|
||||
variant: "default"
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Accessibility Features
|
||||
|
||||
All shadcn/ui components include:
|
||||
- [OK] Proper ARIA attributes
|
||||
- [OK] Keyboard navigation
|
||||
- [OK] Focus management
|
||||
- [OK] Screen reader support
|
||||
- [OK] Reduced motion support
|
||||
|
||||
### Example: Dialog Accessibility
|
||||
|
||||
```tsx
|
||||
<Dialog>
|
||||
{/* Auto-handled: */}
|
||||
{/* - Focus trap */}
|
||||
{/* - ESC to close */}
|
||||
{/* - aria-labelledby */}
|
||||
{/* - Backdrop click to close */}
|
||||
<DialogContent>
|
||||
<DialogHeader>
|
||||
<DialogTitle>Title (used for aria-labelledby)</DialogTitle>
|
||||
</DialogHeader>
|
||||
</DialogContent>
|
||||
</Dialog>
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Always Use Labels with Inputs
|
||||
|
||||
```tsx
|
||||
[OK] Good
|
||||
<div>
|
||||
<Label htmlFor="username">Username</Label>
|
||||
<Input id="username" />
|
||||
</div>
|
||||
|
||||
[ERROR] Bad
|
||||
<Input placeholder="Username" /> {/* Placeholder is not a label */}
|
||||
```
|
||||
|
||||
### 2. Provide Accessible Names
|
||||
|
||||
```tsx
|
||||
[OK] Good
|
||||
<Button aria-label="Close menu">
|
||||
<X className="h-4 w-4" />
|
||||
</Button>
|
||||
|
||||
[ERROR] Bad
|
||||
<Button>
|
||||
<X className="h-4 w-4" /> {/* No text or aria-label */}
|
||||
</Button>
|
||||
```
|
||||
|
||||
### 3. Handle Loading States
|
||||
|
||||
```tsx
|
||||
<Button disabled={isLoading}>
|
||||
{isLoading ? "Loading..." : "Submit"}
|
||||
</Button>
|
||||
```
|
||||
|
||||
### 4. Use Semantic HTML
|
||||
|
||||
```tsx
|
||||
[OK] Good
|
||||
<form onSubmit={handleSubmit}>
|
||||
<Button type="submit">Submit</Button>
|
||||
</form>
|
||||
|
||||
[ERROR] Bad
|
||||
<div onClick={handleSubmit}>
|
||||
<Button type="button">Submit</Button>
|
||||
</div>
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- **Official Docs**: https://ui.shadcn.com
|
||||
- **Component Examples**: https://ui.shadcn.com/examples
|
||||
- **Radix UI Docs**: https://radix-ui.com
|
||||
- **GitHub**: https://github.com/shadcn-ui/ui
|
||||
|
||||
## Integration with This Skill
|
||||
|
||||
The skill installs these baseline components automatically:
|
||||
1. `button` - Primary actions
|
||||
2. `card` - Content containers
|
||||
3. `input` - Form inputs
|
||||
4. `label` - Form labels
|
||||
5. `dialog` - Modals
|
||||
6. `separator` - Visual dividers
|
||||
|
||||
Additional components can be added as needed:
|
||||
```bash
|
||||
npx shadcn-ui add [component-name]
|
||||
```
|
||||
Reference in New Issue
Block a user