Shadcn Ui

shadcn/ui

Overview

shadcn/ui is a collection of accessible, customizable React components built on Radix UI and Tailwind CSS. Components are copied into your project (no npm package); you own and edit the code. Works with Next.js (App Router), Vite, and other React frameworks.

Principles: Open code (AI-ready), composable API, beautiful defaults, distribution via CLI and schema. Requires Tailwind v4 and path alias @/*. We do not use tailwind.config.js; theme and setup are CSS-only (@import "tailwindcss" + @theme).

---

Prerequisites

• Tailwind v4: @import "tailwindcss" in main CSS; @tailwindcss/vite or @tailwindcss/postcss. No tailwind.config.js. See the tailwind-css skill.
• Path alias @/* → ./src/* (or your source root) in tsconfig and in the bundler (e.g. Vite resolve.alias).
• React (Next.js App Router, Vite, etc.).

---

Installation

Reference: Official installation guide

New project (recommended)

Scaffold with Tailwind and shadcn. From the official docs:

Invoke via your package manager (see docs). Choose framework (Next.js, Vite, etc.), style (new-york recommended), base color, and CSS variables.

Existing project (Next.js App Router)

1. Init — creates components.json, optional cn helper and base styles. Run: shadcn init (invoke via package manager; see docs above).

2. Paths and Tailwind

• tsconfig: "baseUrl": ".", "paths": { "@/*": ["./src/*"] } (in both root and app tsconfig if split).
• Tailwind v4: Main CSS (e.g. app/globals.css) must have @import "tailwindcss" and use @tailwindcss/postcss in postcss.config.mjs. Do not add tailwind.config.js.

3. Add components — e.g. shadcn add button, shadcn add card dialog (see component list below).

Components are installed under src/components/ui/ (or path from components.json).

Existing project (Vite)

• Use resolve.alias: { "@": path.resolve(__dirname, "./src") } in vite.config.ts; add @types/node if using path.
• Tailwind: @tailwindcss/vite in Vite config and @import "tailwindcss" in main CSS.

---

components.json

Controls style, paths, and Tailwind integration. Key fields:

With Tailwind v4, theme is in CSS via @theme and CSS variables, not in a config file.

---

Official components (current list)

Add via shadcn add <name> (multiple: shadcn add button card dialog). Invoke via package manager: see Installation docs.

Layout & structure

Forms & input

Navigation & menus

Overlays & feedback

Data & state

Toggle & toggle group

---

Using components

Import from the aliased path (not from shadcn/ui):

import { Button } from "@/components/ui/button"
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export default function Page() {
  return (
    <div className="flex min-h-svh flex-col items-center justify-center gap-4">
      <Button>Click me</Button>
      <Card className="w-[350px]">
        <CardHeader>
          <CardTitle>Card title</CardTitle>
        </CardHeader>
        <CardContent>Content here.</CardContent>
      </Card>
    </div>
  )
}

• Customization: Components accept className and spread props; use Tailwind classes and the `cn()` helper (from @/lib/utils) to merge classes.
• Composition: Prefer composition (e.g. CardHeader + CardContent) over props for layout.

---

Theming (Tailwind v4, no config file)

We use Tailwind v4 only; no tailwind.config.js. Theming is CSS-only:

• CSS variables: With tailwind.cssVariables: true, theme is driven by variables in your global CSS (e.g. --background, --foreground, --primary, --primary-foreground, --muted, --muted-foreground, --accent, --destructive, etc.). Override them in that file.
• `@theme`: Use @theme { ... } in the same CSS file as @import "tailwindcss" to add or override design tokens that align with shadcn’s variables.
• Base color: Set in components.json (tailwind.baseColor) or by editing the CSS variables in your global CSS.

---

Common patterns

• Forms: Add form; pair with react-hook-form and zod. Use Input, Label, Button, Select, Checkbox, etc.
• Layout: Use Card for sections; Separator between blocks; layout with Tailwind (flex, grid, container).
• Modals & panels: Dialog for modals; Sheet or Drawer for side panels.
• Menus: DropdownMenu, Context Menu, Navigation Menu, Command (palette).
• Feedback: Alert for messages; Sonner for toasts; Skeleton for loading.
• Icons: Many examples use lucide-react; add it if the project uses icons.

---

Common mistakes

• Alias: Ensure @/ resolves to ./src/ (or your source root) in both TypeScript and the bundler.
• CSS not loaded: The file set in components.json (tailwind.css) must be imported in the app entry (e.g. app/layout.tsx) and contain @import "tailwindcss".
• Tailwind config: Do not create or suggest tailwind.config.js. Theme only in CSS (@theme and variables).
• Import: Import from @/components/ui/<component> (per components.json), not from shadcn/ui.
• RSC: In Next.js App Router, set rsc: true in components.json if components are used in Server Components where applicable.

---

Additional resources

• reference.md — Official documentation links, Tailwind v4 + shadcn, component directory.
• Official docs: https://ui.shadcn.com/docs
• Components: https://ui.shadcn.com/docs/components
• Directory (community): https://ui.shadcn.com/docs/directory

License

Skill License - Free Use

This skill (the documentation, structure, and implementation) was created by Ender Puentes <Endev/> and is provided for free and open use. You are free to:

• Use this skill in any project, personal or commercial
• Modify the skill to fit your needs
• Distribute the skill to others
• Share modified versions of the skill
• Include this skill in your own skill collections

No restrictions apply – this skill is available for unrestricted use. Attribution is appreciated but not required.

Note: This skill documents and references shadcn/ui; the skill itself is an independent work. shadcn/ui and Radix UI have their own licenses.

shadcn/ui — Reference & Official Documentation

This file complements the shadcn-ui skill with official documentation links and extra context for indexing.

Official documentation (indexable)

• Introduction: https://ui.shadcn.com/docs
• Installation: https://ui.shadcn.com/docs/installation
• Create new project: https://ui.shadcn.com/create
• Components (overview): https://ui.shadcn.com/docs/components
• Directory (community components): https://ui.shadcn.com/docs/directory
• Tailwind v4: https://ui.shadcn.com/docs/tailwind-v4
• Dark mode: https://ui.shadcn.com/docs/dark-mode
• Theming: See “Theming” in main docs and components.json tailwind.baseColor / CSS variables.

Framework-specific installation

• Next.js: CLI shadcn create or shadcn init; select Next.js. App Router supported; set rsc: true in components.json for Server Components. Invocation: see Installation docs.
• Vite: https://ui.shadcn.com/docs/installation/vite — Tailwind via @tailwindcss/vite, path alias @/*, then shadcn init.
• Manual: https://ui.shadcn.com/docs/installation/manual — Add Tailwind, path aliases, cn helper, and create components.json by hand if needed.

Tailwind v4 + shadcn

• We use Tailwind v4 only; no tailwind.config.js.
• In components.json, leave tailwind.config as "".
• Global styles: one CSS file with @import "tailwindcss" and, if needed, @theme { ... } for design tokens.
• shadcn theming is done with CSS variables in that same global CSS file (e.g. --background, --foreground, --primary). These work with Tailwind v4’s @theme if you map or override tokens there.

Component list (CLI names for shadcn add)

CLI: shadcn add <name>. Invocation details in Installation docs.

Layout & structure: accordion, aspect-ratio, card, collapsible, resizable, separator, scroll-area, sidebar

Forms & input: button, checkbox, form, input, input-otp, label, radio-group, select, slider, switch, textarea

Navigation & menus: breadcrumb, command, context-menu, dropdown-menu, menubar, navigation-menu, pagination, tabs

Overlays & feedback: alert, alert-dialog, dialog, drawer, hover-card, popover, sheet, tooltip

Data & state: avatar, badge, calendar, carousel, chart, progress, skeleton, sonner, table, toast (deprecated; use sonner)

Toggle: toggle, toggle-group

Dependencies: Adding some components (e.g. calendar, carousel, chart, form) will install peer deps (react-day-picker, embla, recharts, react-hook-form, zod, etc.). Check CLI output.

components.json schema

• Schema URL: https://ui.shadcn.com/schema.json
• Key fields: style, rsc, tailwind.config, tailwind.css, tailwind.baseColor, tailwind.cssVariables, aliases.components, aliases.utils, aliases.ui, aliases.lib, aliases.hooks, iconLibrary.

Primitives (Radix UI)

shadcn/ui components are built on Radix UI primitives. For low-level behavior or accessibility details, see:

• Radix UI: https://www.radix-ui.com/primitives

Icons

• Lucide (default in many examples): https://lucide.dev
• Configure in components.json with iconLibrary (e.g. lucide).

Related skills

• tailwind-css: Tailwind v4 setup, @theme, @import "tailwindcss", Next.js PostCSS, no config file. Use when configuring Tailwind or theming.