Source of Truth

This is not a component library. It is how you build your component library.

You know how most traditional component libraries work: you install a package from NPM, import the components, and use them in your app.

This approach works well until you need to customize a component to fit your design system or require one that is not included in the library. Often, you end up wrapping library components, writing workarounds to override styles, or mixing components from different libraries with incompatible APIs.

This is what shadcn/ui aims to solve. It is built around the following principles:

Open Code: The top layer of your component code is open for modification.
Composition: Every component uses a common, composable interface, making them predictable.
Distribution: A flat-file schema and command-line tool make it easy to distribute components.
Beautiful Defaults: Carefully chosen default styles, so you get great design out-of-the-box.
AI-Ready: Open code for LLMs to read, understand, and improve.

Open Code

shadcn/ui hands you the actual component code. You have full control to customize and extend the components to your needs. This means:

Full Transparency: You see exactly how each component is built.
Easy Customization: Modify any part of a component to fit your design and functionality requirements.
AI Integration: Access to the code makes it straightforward for LLMs to read, understand, and even improve your components.

In a typical library, if you need to change a button's behavior, you have to override styles or wrap the component. With shadcn/ui, you simply edit the button code directly.

Composition

Every component in shadcn/ui shares a common, composable interface. If a component does not exist, we bring it in, make it composable, and adjust its style to match and work with the rest of the design system.

A shared, composable interface means it's predictable for both your team and LLMs. You are not learning different APIs for every new component. Even for third-party ones.

Distribution

shadcn/ui is also a code distribution system. It defines a schema for components and a CLI to distribute them.

Schema: A flat-file structure that defines the components, their dependencies, and properties.
CLI: A command-line tool to distribute and install components across projects with cross-framework support.

You can use the schema to distribute your components to other projects or have AI generate completely new components based on existing schema.

Beautiful Defaults

shadcn/ui comes with a large collection of components that have carefully chosen default styles. They are designed to look good on their own and to work well together as a consistent system:

Good Out-of-the-Box: Your UI has a clean and minimal look without extra work.
Unified Design: Components naturally fit with one another. Each component is built to match the others, keeping your UI consistent.
Easily Customizable: If you want to change something, it's simple to override and extend the defaults.

AI-Ready

The design of shadcn/ui makes it easy for AI tools to work with your code. Its open code and consistent API allow AI models to read, understand, and even generate new components.

An AI model can learn how your components work and suggest improvements or even create new components that integrate with your existing design.

CLI Reference

init

Use the init command to initialize configuration and dependencies for an existing project, or create a new project with --name.

The init command installs dependencies, adds the cn util and configures CSS variables for the project.

npx shadcn@latest init

Options

Usage: shadcn init [options] [components...]

initialize your project and install dependencies

Arguments:
  components                 names, url or local path to component

Options:
  -t, --template <template>  the template to use. (next, vite, start, react-router, laravel, astro)
  -b, --base <base>          the component library to use. (radix, base)
  -p, --preset [name]        use a preset configuration
  -y, --yes                  skip confirmation prompt. (default: true)
  -d, --defaults             use default configuration: --template=next --preset=nova (default: false)
  -f, --force                force overwrite of existing configuration. (default: false)
  -c, --cwd <cwd>            the working directory. defaults to the current directory.
  -n, --name <name>          the name for the new project.
  -s, --silent               mute output. (default: false)
  --css-variables            use css variables for theming. (default: true)
  --no-css-variables         do not use css variables for theming.
  --monorepo                 scaffold a monorepo project.
  --no-monorepo              skip the monorepo prompt.
  --rtl                      enable RTL support.
  --no-rtl                   disable RTL support.
  --reinstall                re-install existing UI components.
  --no-reinstall             do not re-install existing UI components.
  -h, --help                 display help for command

The create command is an alias for init:

npx shadcn@latest create

add

Use the add command to add components and dependencies to your project.

npx shadcn@latest add [component]

Options

Usage: shadcn add [options] [components...]

add a component to your project

Arguments:
  components           name, url or local path to component

Options:
  -y, --yes            skip confirmation prompt. (default: false)
  -o, --overwrite      overwrite existing files. (default: false)
  -c, --cwd <cwd>      the working directory. defaults to the current directory.
  -a, --all            add all available components (default: false)
  -p, --path <path>    the path to add the component to.
  -s, --silent         mute output. (default: false)
  --dry-run            preview changes without writing files. (default: false)
  --diff [path]        show diff for a file.
  --view [path]        show file contents.
  -h, --help           display help for command

apply

Use the apply command to apply a preset to an existing project.

npx shadcn@latest apply --preset a2r6bw

You can apply only the theme or fonts from a preset without reinstalling UI components:

npx shadcn@latest apply --preset a2r6bw --only theme

Supported values for --only are theme and font.

Options

Usage: shadcn apply [options] [preset]

apply a preset to an existing project

Arguments:
  preset             the preset to apply

Options:
  --preset <preset>  preset configuration to apply
  --only [parts]     apply only parts of a preset: theme, font
  -y, --yes          skip confirmation prompt. (default: false)
  -c, --cwd <cwd>    the working directory. defaults to the current directory.
  -s, --silent       mute output. (default: false)
  -h, --help         display help for command

view

Use the view command to view items from the registry before installing them.

npx shadcn@latest view [item]

You can view multiple items at once:

npx shadcn@latest view button card dialog

Or view items from namespaced registries:

npx shadcn@latest view @acme/auth @v0/dashboard

Options

Usage: shadcn view [options] <items...>

view items from the registry

Arguments:
  items            the item names or URLs to view

Options:
  -c, --cwd <cwd>  the working directory. defaults to the current directory.
  -h, --help       display help for command

search

Use the search command to search for items from registries.

npx shadcn@latest search [registry]

You can search with a query:

npx shadcn@latest search @shadcn -q "button"

Or search multiple registries at once:

npx shadcn@latest search @shadcn @v0 @acme

The list command is an alias for search:

npx shadcn@latest list @acme

Options

Usage: shadcn search|list [options] <registries...>

search items from registries

Arguments:
  registries             the registry names or urls to search items from. Names
                         must be prefixed with @.

Options:
  -c, --cwd <cwd>        the working directory. defaults to the current directory.
  -q, --query <query>    query string
  -l, --limit <number>   maximum number of items to display per registry (default: "100")
  -o, --offset <number>  number of items to skip (default: "0")
  -h, --help             display help for command

build

Use the build command to generate the registry JSON files.

npx shadcn@latest build

This command reads the registry.json file and generates the registry JSON files in the public/r directory.

Options

Usage: shadcn build [options] [registry]

build components for a shadcn registry

Arguments:
  registry             path to registry.json file (default: "./registry.json")

Options:
  -o, --output <path>  destination directory for json files (default: "./public/r")
  -c, --cwd <cwd>      the working directory. defaults to the current directory.
  -h, --help           display help for command

To customize the output directory, use the --output option.

npx shadcn@latest build --output ./public/registry

docs

Use the docs command to fetch documentation and API references for components.

npx shadcn@latest docs [component]

Options

Usage: shadcn docs [options] [component]

fetch documentation and API references for components

Arguments:
  component          the component to get docs for

Options:
  -c, --cwd <cwd>    the working directory. defaults to the current directory.
  -b, --base <base>  the base to use either 'base' or 'radix'. defaults to project base.
  --json             output as JSON. (default: false)
  -h, --help         display help for command

info

Use the info command to get information about your project.

npx shadcn@latest info

Options

Usage: shadcn info [options]

get information about your project

Options:
  -c, --cwd <cwd>  the working directory. defaults to the current directory.
  --json            output as JSON. (default: false)
  -h, --help        display help for command

migrate

Use the migrate command to run migrations on your project.

npx shadcn@latest migrate [migration]

Available Migrations

| Migration | Description | | --------- | ------------------------------------------------------- | | icons | Migrate your UI components to a different icon library. | | radix | Migrate to radix-ui. | | rtl | Migrate your components to support RTL (right-to-left). |

Options

Usage: shadcn migrate [options] [migration] [path]

run a migration.

Arguments:
  migration        the migration to run.
  path             optional path or glob pattern to migrate.

Options:
  -c, --cwd <cwd>  the working directory. defaults to the current directory.
  -l, --list       list all migrations. (default: false)
  -y, --yes        skip confirmation prompt. (default: false)
  -h, --help       display help for command

migrate rtl

The rtl migration transforms your components to support RTL (right-to-left) languages.

npx shadcn@latest migrate rtl

This will:

Update components.json to set rtl: true
Transform physical CSS properties to logical equivalents (e.g., ml-4 to ms-4, text-left to text-start)
Add rtl: variants where needed (e.g., space-x-4 to space-x-4 rtl:space-x-reverse)

Migrate specific files

You can migrate specific files or use glob patterns:

# Migrate a specific file
npx shadcn@latest migrate rtl src/components/ui/button.tsx

# Migrate files matching a glob pattern
npx shadcn@latest migrate rtl "src/components/ui/**"

If no path is provided, the migration will transform all files in your ui directory (from components.json).

migrate radix

The radix migration updates your imports from individual @radix-ui/react-* packages to the unified radix-ui package.

npx shadcn@latest migrate radix

This will:

Transform imports from @radix-ui/react-* to radix-ui
Add the radix-ui package to your package.json

Before

import * as DialogPrimitive from "@radix-ui/react-dialog"
import * as SelectPrimitive from "@radix-ui/react-select"

After

import { Dialog as DialogPrimitive, Select as SelectPrimitive } from "radix-ui"

Migrate specific files

You can migrate specific files or use glob patterns:

# Migrate a specific file.
npx shadcn@latest migrate radix src/components/ui/dialog.tsx

# Migrate files matching a glob pattern.
npx shadcn@latest migrate radix "src/components/ui/**"

If no path is provided, the migration will transform all files in your ui directory (from components.json).

Once complete, you can remove any unused @radix-ui/react-* packages from your package.json.

Your Project is Ready

Here are a few things you can do to get started building with shadcn/ui.

Add Components

Use the CLI to add components to your project.

npx shadcn@latest add button

Then import and use it in your code.

import { Button } from "@/components/ui/button"

export default function Home() {
  return <Button>Click me</Button>
}

Unlike traditional component libraries, shadcn/ui adds the component source code directly to your project under components/ui/. You own the code and can customize it however you want.

You can add multiple components at once or add all available components.

npx shadcn@latest add button card input label

npx shadcn@latest add --all

Customize Your Theme

You can edit your theme directly in your CSS file. Learn more about Theming and how to use CSS variables or utility classes.

If you want to try a new preset, you can create a custom theme visually on ui.shadcn.com and apply it to your project using a preset code.

npx shadcn@latest init --preset [CODE]

Add a Block

You can add a block to your project using the CLI.

npx shadcn@latest add login-03

This will add the login-03 block to your project. Import and use it in your code.

import { Login03 } from "@/components/login-03"

export default function Home() {
  return <Login03 />
}

Install from Registries

shadcn/ui has a growing ecosystem of community registries. You can install components from any registry URL using the CLI.

npx shadcn@latest add @[registry]/[name]

Use AI to Build

shadcn/ui is designed to work with AI. Your AI assistant can read the component source code in your project, understand the APIs, and compose them together to build pages and features.

Here are some example prompts to try:

"Create a signup page with a form for entering name, email and password."
"Create a settings page with a form for updating profile information."
"Build a dashboard with a header, stats cards, and a data table."

Install the shadcn Skills

Install the shadcn skill in your AI assistant. This will give your AI assistant access to the full component registry, documentation, and search.

npx skills add shadcn/ui

Connect the MCP Server

The shadcn MCP server gives your AI assistant access to the full component registry, documentation, and search. Connect it in your editor for the best experience.

npx shadcn@latest mcp init

JavaScript Support

This project and the components are written in TypeScript. We recommend using TypeScript for your project as well.

However we provide a JavaScript version of the components as well. The JavaScript version is available via the CLI.

To opt-out of TypeScript, you can use the tsx flag in your components.json file.

{
  "style": "new-york",
  "rsc": false,
  "tsx": false,
  "tailwind": {
    "config": "",
    "css": "src/app/globals.css",
    "baseColor": "zinc",
    "cssVariables": true
  },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

To configure import aliases, you can use the following jsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

MCP Server

The shadcn MCP Server allows AI assistants to interact with items from registries. You can browse available components, search for specific ones, and install them directly into your project using natural language.

For example, you can ask an AI assistant to "Build a landing page using components from the acme registry" or "Find me a login form from the shadcn registry".

Registries are configured in your project's components.json file.

{
  "registries": {
    "@acme": "https://acme.com/r/{name}.json"
  }
}