xonecas.io
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![Preview](http://https:%2F%2Fcontext7.com%2Fwebsites%2Fshadcn_io%2Fllms.txt/thumbnail.jpg)
483{isHovering && (
484
485
486![Full size](http://https:%2F%2Fcontext7.com%2Fwebsites%2Fshadcn_io%2Fllms.txt/full-size.jpg)
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.