Introduction

shadcn/ui is a collection of beautifully-designed, accessible components paired with a revolutionary code distribution platform. Compatible with all major frameworks and AI models. Open Source. Open Code.

This isn't just another component library—it's a new approach to building your own component system.

The Traditional Problem

Traditional component libraries follow a familiar pattern: install from NPM, import components, use in your application. This works until you need to:

• Customize components beyond what props allow
• Add features that aren't supported
• Match your specific design system requirements
• Mix components from different libraries with incompatible APIs

You end up fighting the library—wrapping components, overriding styles with !important, maintaining patches, or abandoning the library altogether.

A Different Philosophy

shadcn/ui solves these problems through five core principles:

1. Open Code Architecture

Unlike traditional libraries that hide implementation details, shadcn/ui gives you the actual source code. Every component lives in your codebase, fully visible and modifiable:

• Complete Transparency: See exactly how components work, no black boxes
• Direct Customization: Modify any aspect without fighting abstractions
• No Version Lock-in: Your components evolve with your needs, not library releases
• AI-Compatible: LLMs can read, understand, and enhance your components directly

When you need to change a button's behavior, you don't override—you edit the button itself.

2. Composable Design System

All components share a unified, predictable interface built on consistent patterns:

• Predictable APIs: Learn once, apply everywhere
• Seamless Integration: Components work together naturally
• Framework Agnostic: Same patterns across React, Vue, and other frameworks
• Extensible Foundation: Add new components that fit perfectly with existing ones

This consistency benefits both developers and AI tools—reducing cognitive load and enabling intelligent code generation.

3. Modern Distribution

shadcn/ui revolutionizes component distribution with a flat-file schema and powerful CLI:

Schema-Driven

• Declarative component definitions
• Dependency management
• Cross-framework support
• Version-free distribution

CLI Workflow

npx shadcn@latest add dialog

Components are copied directly into your project—no package dependencies, no version conflicts.

4. Beautiful by Default

Every component features meticulously crafted default styles:

• Production-Ready: Professional design out of the box
• Cohesive System: Components share visual language and spacing
• Dark Mode Support: Built-in theme switching
• Tailwind-Powered: Utility-first CSS for rapid customization

Start with beautiful defaults, then make them yours.

5. AI-Native Development

Built for the age of AI-assisted development:

• LLM-Readable: Clean, documented code that AI models understand
• Generation-Ready: Consistent patterns enable reliable AI code generation
• Improvement-Friendly: AI can suggest enhancements based on your usage
• Context-Aware: Open code means AI has full visibility into implementation

Your AI assistant becomes a true collaborator, not just a code completer.

Getting Started

Installation

Choose your framework and install your first component:

# React
npx shadcn@latest init
npx shadcn@latest add button

# Vue (coming soon)
npx shadcn-vue@latest init
npx shadcn-vue@latest add button

Your First Component

Components are installed directly into your project:

// components/ui/button.tsx
import * as React from "react"
import { cn } from "@/lib/utils"

export function Button({ className, ...props }) {
  return (
    <button
      className={cn(
        "inline-flex items-center justify-center rounded-md text-sm font-medium",
        className
      )}
      {...props}
    />
  )
}

Now customize it to match your brand—change colors, adjust spacing, add animations. It's your code.

Why This Matters

For Developers

• Full Control: No more fighting with library limitations
• Better DX: Understand what you're using, debug effectively
• Future-Proof: Your components evolve with your needs
• Learn by Reading: See how professional components are built

For Teams

• Shared Ownership: Everyone can understand and modify components
• Consistent Codebase: Same patterns throughout your application
• Reduced Dependencies: Fewer external packages to manage
• Design System Freedom: Build exactly what you need

For Products

• Performance: Only ship the code you use
• Accessibility: WCAG-compliant components by default
• Maintainability: Direct control over your UI layer
• Scalability: Components that grow with your product

What's Next

Explore our component collection, each crafted with the same attention to detail:

• Components: Browse the full collection
• Themes: Customize your design system
• Examples: See components in action
• Templates: Start with production-ready layouts

Join the Revolution

shadcn/ui represents a fundamental shift in how we build and distribute UI components. It's not about using our components—it's about making them yours.

Ready to take control of your component library? Start with a single component and experience the difference.

npx shadcn@latest add

Welcome to the future of component development. Welcome to shadcn/ui.