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](https://context7.com/websites/shadcn_io/llms.txt/thumbnail.jpg)
483{isHovering && (
484 
485 
486![Full size](https://context7.com/websites/shadcn_io/llms.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.