556
Bn
bees-nest / files
bees-nest / .opencode / skills / shadcn-ui / reference.md
14.0 KB
1# shadcn.io Component Library 2 3shadcn.io is a comprehensive React UI component library built on shadcn/ui principles, providing developers with production-ready, composable components for modern web applications. The library serves as a centralized resource for React developers who need high-quality UI components with TypeScript support, ranging from basic interactive elements to advanced AI-powered integrations. Unlike traditional component libraries that require package installations, shadcn.io components are designed to be copied directly into your project, giving you full control and customization capabilities. 4 5The library encompasses four major categories: composable UI components (terminal, dock, credit cards, QR codes, color pickers), chart components built with Recharts, animation components with Tailwind CSS integration, and custom React hooks for state management and lifecycle operations. Each component follows best practices for accessibility, performance, and developer experience, with comprehensive TypeScript definitions and Next.js compatibility. The platform emphasizes flexibility and customization, allowing developers to modify components at the source level rather than being constrained by package APIs. 6 7## Core Components 8 9### Terminal Component 10Interactive terminal emulator with typing animations and command execution simulation for developer-focused interfaces. 11 12```tsx 13import { Terminal } from "@/components/ui/terminal" 14 15export default function DemoTerminal() { 16 return ( 17 npm install @repo/terminalInstalling dependencies...npm start 18 ) 19} 20``` 21 22### Dock Component 23macOS-style application dock with smooth magnification effects on hover, perfect for navigation menus. 24 25```tsx 26import { Dock, DockIcon } from "@/components/ui/dock" 27import { Home, Settings, User, Mail } from "lucide-react" 28 29export default function AppDock() { 30 return ( 31 32 ) 33} 34``` 35 36### Credit Card Component 37Interactive 3D credit card component with flip animations for payment forms and card displays. 38 39```tsx 40import { CreditCard } from "@/components/ui/credit-card" 41import { useState } from "react" 42 43export default function PaymentForm() { 44 const [cardData, setCardData] = useState({ 45 number: "4532 1234 5678 9010", 46 holder: "JOHN DOE", 47 expiry: "12/28", 48 cvv: "123" 49 }) 50 51 return ( 52 console.log("Card flipped:", flipped)} 53 /> 54 ) 55} 56``` 57 58### Image Zoom Component 59Zoomable image component with smooth modal transitions for image galleries and product displays. 60 61```tsx 62import { ImageZoom } from "@/components/ui/image-zoom" 63 64export default function ProductGallery() { 65 return ( 66 67 68 ) 69} 70``` 71 72### QR Code Component 73Generate and display customizable QR codes with styling options for links, contact information, and authentication. 74 75```tsx 76import { QRCode } from "@/components/ui/qr-code" 77 78export default function ShareDialog() { 79 const shareUrl = "https://shadcn.io" 80 81 return ( 82 83 84Scan to visit shadcn.io 85 86 87 ) 88} 89``` 90 91### Color Picker Component 92Advanced color selection component supporting multiple color formats (HEX, RGB, HSL) with preview. 93 94```tsx 95import { ColorPicker } from "@/components/ui/color-picker" 96import { useState } from "react" 97 98export default function ThemeCustomizer() { 99 const [color, setColor] = useState("#3b82f6") 100 101 return ( 102 103 104Selected: {color} 105 106) 107} 108``` 109 110## Chart Components 111 112### Bar Chart Component 113Clean bar chart component for data comparison and categorical analysis using Recharts. 114 115```tsx 116import { BarChart } from "@/components/ui/bar-chart" 117 118export default function SalesChart() { 119const data = [ 120{ month: "Jan", sales: 4000, revenue: 2400 }, 121{ month: "Feb", sales: 3000, revenue: 1398 }, 122{ month: "Mar", sales: 2000, revenue: 9800 }, 123{ month: "Apr", sales: 2780, revenue: 3908 }, 124{ month: "May", sales: 1890, revenue: 4800 }, 125{ month: "Jun", sales: 2390, revenue: 3800 } 126] 127 128return ( 129`$${value.toLocaleString()}`} 130yAxisWidth={60} 131/> 132) 133} 134``` 135 136### Line Chart Component 137Smooth line chart for visualizing trends and time-series data with multiple data series support. 138 139```tsx 140import { LineChart } from "@/components/ui/line-chart" 141 142export default function MetricsChart() { 143const data = [ 144{ date: "2024-01", users: 1200, sessions: 3400 }, 145{ date: "2024-02", users: 1800, sessions: 4200 }, 146{ date: "2024-03", users: 2400, sessions: 5800 }, 147{ date: "2024-04", users: 3100, sessions: 7200 }, 148{ date: "2024-05", users: 3800, sessions: 8900 } 149] 150 151return ( 152 153) 154} 155``` 156 157### Pie Chart Component 158Donut chart component for displaying proportional data and percentage distributions. 159 160```tsx 161import { PieChart } from "@/components/ui/pie-chart" 162 163export default function MarketShareChart() { 164const data = [ 165{ name: "Product A", value: 400, fill: "#3b82f6" }, 166{ name: "Product B", value: 300, fill: "#10b981" }, 167{ name: "Product C", value: 300, fill: "#f59e0b" }, 168{ name: "Product D", value: 200, fill: "#ef4444" } 169] 170 171return ( 172`${entry.name}: ${entry.value}`} 173/> 174) 175} 176``` 177 178### Area Chart Component 179Stacked area chart for visualizing volume changes over time with multiple data series. 180 181```tsx 182import { AreaChart } from "@/components/ui/area-chart" 183 184export default function TrafficChart() { 185const data = [ 186{ month: "Jan", mobile: 2000, desktop: 3000, tablet: 1000 }, 187{ month: "Feb", mobile: 2200, desktop: 3200, tablet: 1100 }, 188{ month: "Mar", mobile: 2800, desktop: 3800, tablet: 1300 }, 189{ month: "Apr", mobile: 3200, desktop: 4200, tablet: 1500 }, 190{ month: "May", mobile: 3800, desktop: 4800, tablet: 1800 } 191] 192 193return ( 194 195) 196} 197``` 198 199### Radar Chart Component 200Multi-axis chart for comparing multiple variables across different categories simultaneously. 201 202```tsx 203import { RadarChart } from "@/components/ui/radar-chart" 204 205export default function SkillsChart() { 206const data = [ 207{ skill: "JavaScript", score: 85, industry: 75 }, 208{ skill: "TypeScript", score: 80, industry: 70 }, 209{ skill: "React", score: 90, industry: 80 }, 210{ skill: "Node.js", score: 75, industry: 72 }, 211{ skill: "CSS", score: 88, industry: 78 } 212] 213 214return ( 215 216) 217} 218``` 219 220### Mixed Chart Component 221Combined bar and line chart for displaying multiple data types with different visualization methods. 222 223```tsx 224import { MixedChart } from "@/components/ui/mixed-chart" 225 226export default function PerformanceChart() { 227const data = [ 228{ month: "Jan", revenue: 4000, growth: 5.2 }, 229{ month: "Feb", revenue: 4200, growth: 5.0 }, 230{ month: "Mar", revenue: 4800, growth: 14.3 }, 231{ month: "Apr", revenue: 5200, growth: 8.3 }, 232{ month: "May", revenue: 5800, growth: 11.5 } 233] 234 235return ( 236 237) 238} 239``` 240 241## Animation Components 242 243### Magnetic Effect Component 244Magnetic hover effect that smoothly follows cursor movement for interactive buttons and cards. 245 246```tsx 247import { Magnetic } from "@/components/ui/magnetic" 248 249export default function InteractiveButton() { 250return ( 251 252Hover me 253 254) 255} 256``` 257 258### Animated Cursor Component 259Custom animated cursor with interactive effects and particle trails for immersive experiences. 260 261```tsx 262import { AnimatedCursor } from "@/components/ui/animated-cursor" 263 264export default function Layout({ children }) { 265return ( 266<> 267 268{children} 269 270) 271} 272``` 273 274### Apple Hello Effect Component 275Recreation of Apple's iconic "hello" animation with multi-language text transitions. 276 277```tsx 278import { AppleHello } from "@/components/ui/apple-hello" 279 280export default function WelcomeScreen() { 281const greetings = [ 282{ text: "Hello", lang: "en" }, 283{ text: "Bonjour", lang: "fr" }, 284{ text: "こんにちは", lang: "ja" }, 285{ text: "Hola", lang: "es" }, 286{ text: "你好", lang: "zh" } 287] 288 289return ( 290 291) 292} 293``` 294 295### Liquid Button Component 296Button with fluid liquid animation effect on hover for engaging call-to-action elements. 297 298```tsx 299import { LiquidButton } from "@/components/ui/liquid-button" 300 301export default function CTASection() { 302return ( 303console.log("CTA clicked")} 304> 305Get Started 306 307) 308} 309``` 310 311### Rolling Text Component 312Text animation that creates a rolling effect with smooth character transitions. 313 314```tsx 315import { RollingText } from "@/components/ui/rolling-text" 316 317export default function AnimatedHeading() { 318return ( 319 320) 321} 322``` 323 324### Shimmering Text Component 325Text with animated shimmer effect for attention-grabbing headings and highlights. 326 327```tsx 328import { ShimmeringText } from "@/components/ui/shimmering-text" 329 330export default function Hero() { 331return ( 332 333) 334} 335``` 336 337## React Hooks 338 339### useBoolean Hook 340Enhanced boolean state management with toggle, enable, and disable methods for cleaner component logic. 341 342```tsx 343import { useBoolean } from "@/hooks/use-boolean" 344 345export default function TogglePanel() { 346const modal = useBoolean(false) 347const loading = useBoolean(false) 348 349const handleSubmit = async () => { 350loading.setTrue() 351try { 352await submitForm() 353modal.setFalse() 354} finally { 355loading.setFalse() 356} 357} 358 359return ( 360<> 361Toggle Modal 362{modal.value && ( 363 364 365Status: {loading.value ? "Saving..." : "Ready"} 366 367Submit 368 369 370)} 371 372) 373} 374``` 375 376### useCounter Hook 377Counter hook with increment, decrement, reset, and set functionality for numeric state management. 378 379```tsx 380import { useCounter } from "@/hooks/use-counter" 381 382export default function CartCounter() { 383const quantity = useCounter(0, { min: 0, max: 99 }) 384 385return ( 386 387 388 - 389{quantity.value} 390+ 391 392Reset 393 394 395) 396} 397``` 398 399### useLocalStorage Hook 400Persist state in browser localStorage with automatic serialization and deserialization. 401 402```tsx 403import { useLocalStorage } from "@/hooks/use-local-storage" 404 405export default function UserPreferences() { 406const [theme, setTheme] = useLocalStorage("theme", "light") 407const [settings, setSettings] = useLocalStorage("settings", { 408notifications: true, 409emailUpdates: false 410}) 411 412return ( 413 414 415setTheme(e.target.value)}> 416LightDark setSettings({ 417...settings, 418notifications: e.target.checked 419})} 420/> 421Enable Notifications 422 423 424) 425} 426``` 427 428### useDebounceValue Hook 429Debounce values to prevent excessive updates and API calls during rapid user input. 430 431```tsx 432import { useDebounceValue } from "@/hooks/use-debounce-value" 433import { useState, useEffect } from "react" 434 435export default function SearchBox() { 436const [search, setSearch] = useState("") 437const debouncedSearch = useDebounceValue(search, 500) 438const [results, setResults] = useState([]) 439const [apiCalls, setApiCalls] = useState(0) 440 441useEffect(() => { 442if (debouncedSearch) { 443setApiCalls(prev => prev + 1) 444fetch(`/api/search?q=${debouncedSearch}`) 445.then(res => res.json()) 446.then(setResults) 447} 448}, [debouncedSearch]) 449 450return ( 451 452 453setSearch(e.target.value)} 454placeholder="Search..." 455/> 456 457 458API calls: {apiCalls} 459 460 461) 462} 463``` 464 465### useHover Hook 466Track hover state on elements with customizable enter and leave delays for tooltip and preview functionality. 467 468```tsx 469import { useHover } from "@/hooks/use-hover" 470import { useRef } from "react" 471 472export default function ImagePreview() { 473const hoverRef = useRef(null) 474const isHovering = useHover(hoverRef, { 475enterDelay: 200, 476leaveDelay: 100 477}) 478 479return ( 480 481 482 483{isHovering && ( 484 485 486 487 488)} 489 490 491) 492} 493``` 494 495### useCountdown Hook 496Countdown timer with play, pause, reset controls and completion callbacks for time-limited features. 497 498```tsx 499import { useCountdown } from "@/hooks/use-countdown" 500 501export default function OTPTimer() { 502const countdown = useCountdown({ 503initialSeconds: 60, 504onComplete: () => alert("OTP expired! Request a new code.") 505}) 506 507return ( 508 509 510{countdown.seconds}s 511 512{!countdown.isRunning ? ( 513Start 514) : ( 515Pause 516)} 517Reset 518 519Status: {countdown.isComplete ? "Expired" : countdown.isRunning ? "Active" : "Paused"} 520 521 522) 523} 524``` 525 526## Installation and Usage 527 528### CLI Installation 529Install components directly into your project using the shadcn CLI for instant integration. 530 531```bash 532# Initialize shadcn in your project 533npx shadcn@latest init 534 535# Add individual components 536npx shadcn@latest add terminal 537npx shadcn@latest add dock 538npx shadcn@latest add credit-card 539 540# Add multiple components at once 541npx shadcn@latest add bar-chart line-chart pie-chart 542 543# Add hooks 544npx shadcn@latest add use-boolean use-counter use-local-storage 545``` 546 547### Project Configuration 548Configure your project to work with shadcn.io components using TypeScript and Tailwind CSS. 549 550```typescript 551// tailwind.config.ts 552import type { Config } from "tailwindcss" 553 554const config: Config = { 555darkMode: ["class"], 556content: [ 557"./pages/**/*.{ts,tsx}", 558"./components/**/*.{ts,tsx}", 559"./app/**/*.{ts,tsx}", 560], 561theme: { 562extend: { 563colors: { 564border: "hsl(var(--border))", 565input: "hsl(var(--input))", 566ring: "hsl(var(--ring))", 567background: "hsl(var(--background))", 568foreground: "hsl(var(--foreground))", 569primary: { 570DEFAULT: "hsl(var(--primary))", 571foreground: "hsl(var(--primary-foreground))", 572}, 573}, 574}, 575}, 576plugins: [require("tailwindcss-animate")], 577} 578 579export default config 580``` 581 582## Summary 583 584The shadcn.io component library serves as a comprehensive toolkit for React developers building modern web applications with Next.js and TypeScript. The library's primary use cases include rapid prototyping of user interfaces, building data-rich dashboards with interactive charts, creating engaging user experiences with animations and effects, and implementing common UI patterns without writing boilerplate code. The copy-paste approach gives developers complete ownership of their components, allowing for deep customization while maintaining consistency with shadcn/ui design principles. Components are particularly well-suited for SaaS applications, admin panels, marketing websites, and e-commerce platforms that require professional, accessible UI elements. 585 586Integration patterns center around composability and customization rather than rigid package dependencies. Developers can cherry-pick individual components using the CLI, modify them at the source level to match their design system, and combine them with existing shadcn/ui components for a cohesive interface. The library supports both light and dark themes through CSS variables, integrates seamlessly with Tailwind CSS utility classes, and follows React best practices for performance and accessibility. Custom hooks provide reusable logic patterns that complement the visual components, creating a complete ecosystem for building feature-rich applications. The TypeScript-first approach ensures type safety throughout the development process, while the Recharts integration for data visualization provides powerful charting capabilities without additional configuration overhead.