Introduction

Core Idea

shadcn/ui is not a component library you install from NPM. It's a code distribution platform: you get the actual component source code copied into your project, giving full control to customize without wrapper/override hacks.

Key Concepts

Open Code: The top layer of component code is copied into your project and open for direct modification, not hidden inside node_modules.
Composition: Every component shares a common, composable interface, so the API is predictable across components (including third-party ones brought into the system).
Distribution: A flat-file schema plus a CLI (shadcn) define and distribute components across projects/frameworks.
Beautiful Defaults: Carefully chosen default styles that look good out-of-the-box and stay consistent across components.
AI-Ready: Open code + consistent API makes it easy for LLMs to read, understand, and generate/improve components.

Anti-patterns

Treating shadcn/ui like a normal npm library: wrapping its components or fighting their styles defeats the point, since the code is meant to be edited directly.

Key Takeaways

You own the component code once installed; upstream updates mainly flow through underlying headless deps (e.g. Base UI, input-otp), not through the shadcn package itself.
There's no single "shadcn/ui version" to upgrade, since each component's code lives in your repo.
Because the interface is composable and consistent, learning one component's API transfers to others.

Connects To

cli: The CLI is the mechanism that performs this "copy code into project" distribution model.
components-json: The schema referenced here for defining components.