Install shadcn/ui skill
Run 'npx skills add shadcn/ui' to install the shadcn skill into your project. Once installed, your AI assistant automatically loads it when working with shadcn/ui components.
blocks/setup
167 notes in this subject, read out of this brain and free to use. This is page 2 of 3.
Skills provide AI context about shadcn/ui
Skills give AI assistants like Claude Code project-aware context about shadcn/ui components, patterns, and best practices. They enable the assistant to find, install, compose, and customize components using the correct APIs and patterns for your project.
Skill reads components.json for project configuration
The skill reads your project's components.json file and provides the assistant with your framework, aliases, installed components, icon library, and base library so it can generate correct code on the first try.
Skill provides theming and customization knowledge
The skill includes knowledge of how CSS variables, OKLCH colors, dark mode, custom colors, border radius, and component variants work. It includes guidance for both Tailwind v3 and v4.
Skill includes MCP Server setup knowledge
The skill includes setup and tools for the shadcn MCP server, which lets AI assistants search, browse, and install components from registries.
Skill activates when components.json is present
The skill activates when it finds a components.json file in your project. It then runs 'shadcn info --json' to read your project configuration and injects the result into the assistant's context.
Assistant follows shadcn composition rules
The assistant follows shadcn/ui composition rules: using FieldGroup for forms, ToggleGroup for option sets, semantic colors, and correct base-specific APIs.
Tailwind v4 and React 19 support
The CLI can now initialize projects with Tailwind v4. Full support for the new @theme directive and @theme inline option is included. All components are updated for Tailwind v4 and React 19.
Component changes for Tailwind v4
forwardRefs have been removed and types adjusted. Every primitive now has a data-slot attribute for styling. Component styles have been fixed and cleaned up. Buttons now use the default cursor.
Styling deprecations for Tailwind v4
The default style is deprecated. New projects will use new-york. HSL colors are now converted to OKLCH. The tailwindcss-animate plugin is deprecated in favor of tw-animate-css.
Toast component deprecation
The toast component is deprecated in favor of sonner.
Backward compatibility with Tailwind v3 and React 18
This is a non-breaking change. Existing apps with Tailwind v3 and React 18 will still work. When you add new components, they'll still be in v3 and React 18 until you upgrade. Only new projects start with Tailwind v4 and React 19.
Update CSS variables for Tailwind v4
Move :root and .dark out of @layer base. Wrap color values in hsl(). Add the inline option to @theme i.e @theme inline. Remove the hsl() wrappers from @theme and use var() references instead. Example: --color-background: var(--background) instead of hsl(var(--background)).
Update chart colors for Tailwind v4
Remove the hsl() wrapper from chartConfig values. Change from "hsl(var(--chart-1))" to "var(--chart-1)".
Use new size-* utility in Tailwind v4
The new size-* utility added in Tailwind v3.4 is now fully supported by tailwind-merge. Replace w-* h-* with the new size-* utility, e.g., replace "w-4 h-4" with "size-4".
Update dependencies for Tailwind v4
Run: pnpm up "@radix-ui/*" cmyk lucide-react recharts tailwind-merge clsx --latest
Remove forwardRef pattern in components
Replace React.forwardRef<...> with React.ComponentProps<...>. Remove ref={ref} from the component. Add a data-slot attribute for styling. Optionally convert to a named function and remove displayName.
Migrate tailwindcss-animate to tw-animate-css
Remove tailwindcss-animate from dependencies. Remove @plugin 'tailwindcss-animate' from globals.css. Install tw-animate-css as a dev dependency. Add @import "tw-animate-css" to globals.css.
Dark mode color updates for Tailwind v4
New dark mode colors have been introduced to be more accessible. For existing Tailwind v4 projects (not upgraded ones), you can update components by re-adding them using the CLI with npx shadcn@latest add --all --overwrite, then update colors to new OKLCH colors in globals.css. Upgraded projects are not affected and can continue using old dark mode colors.
Supported frameworks for Tailwind v4
Framework-specific guides are available for: Next.js, Vite, Laravel, React Router, Astro, TanStack Start, Gatsby, and Manual setup.
CSS variable structure for Tailwind v4
CSS variables should be structured as: :root { --background: hsl(0 0% 100%); --foreground: hsl(0 0% 3.9%); } .dark { --background: hsl(0 0% 3.9%); --foreground: hsl(0 0% 98%); } @theme inline { --color-background: var(--background); --color-foreground: var(--foreground); }
Tailwind v4 upgrade path for existing projects
Follow the official Tailwind v4 upgrade guide at https://tailwindcss.com/docs/upgrade-guide. Use the @tailwindcss/upgrade@next codemod to remove deprecated utility classes and update tailwind config. Ensure your project is ready for the upgrade as Tailwind v4 uses bleeding-edge browser features designed for modern browsers. Reference Tailwind v4 Compatibility Docs before upgrading.
Install remix-themes package
To add theme switching capabilities to a Remix app, install the remix-themes package using `npm install remix-themes`.
Forms framework options in shadcn/ui
shadcn/ui provides form documentation for multiple frameworks. The currently documented form libraries are React Hook Form, TanStack Form, and Formisch. useActionState support is listed as coming soon.
Form documentation structure
To build forms with shadcn/ui, users start by selecting their framework of choice, then follow specific instructions for that framework paired with the corresponding form library.
Astro installation options
Three setup paths exist for shadcn/ui with Astro: using shadcn/create to build a preset visually, using the CLI to scaffold a new project, or configuring manually in an existing Astro project.
shadcn/create Astro setup flow
Open shadcn/create at /create?template=astro to build your preset visually by choosing style, colors, fonts, and icons. Click Create Project and copy the generated command which follows the format: npx shadcn@latest init --preset [CODE] --template astro. The exact command includes selected options such as --base, --monorepo, or --rtl.
Astro component import path
Components in Astro are imported from @/components/ui/[component-name]. In monorepo layouts, import from @workspace/ui/components/card instead. The monorepo layout at apps/web/src/layouts/main.astro already imports @workspace/ui/globals.css.
Astro existing project requirements
Before adding shadcn/ui to an existing Astro project, ensure Tailwind CSS and React integration are configured. The Tailwind starter loads the global stylesheet through src/layouts/main.astro; keep that layout in place or ensure your page imports @/styles/global.css.
tsconfig.json path alias for Astro
Add the following to tsconfig.json to resolve @/* paths: "baseUrl": ".", "paths": { "@/*": ["./src/*"] }. Skip this step if your project already has the @/* alias configured.
Astro new project setup command
To create a new Astro project with Tailwind CSS and React integration, run: npm create astro@latest astro-app -- --template with-tailwindcss --install --add react --git
Card component import example in Astro
Import Card components in Astro pages like this: ```astro --- import Layout from "@/layouts/main.astro" import { Card, CardContent, CardDescription, CardHeader, CardTitle, } from "@/components/ui/card" --- <Layout> <Card className="max-w-sm"> <CardHeader> <CardTitle>Project Overview</CardTitle> <CardDescription> Track progress and recent activity for your Astro app. </CardDescription> </CardHeader> <CardContent> Your design system is ready. Start building your next component. </CardContent> </Card> </Layout> ```
Button component import example in Astro
Import Button component in Astro pages like this: ```astro --- import Layout from "@/layouts/main.astro" import { Button } from "@/components/ui/button" --- <Layout> <div class="grid h-screen place-items-center content-center"> <Button>Button</Button> </div> </Layout> ```
Gatsby installation - create project with create-gatsby
To create a new Gatsby project, run `npm init gatsby`.
Gatsby installation - configure TypeScript and Tailwind CSS
When running `npm init gatsby`, select TypeScript for the language and Tailwind CSS as the styling system. Make choices on other options as desired.
Gatsby tsconfig.json path resolution
Add the following to tsconfig.json to resolve the @ path alias: set "baseUrl" to "." and add "@/*": ["./src/*"] to the "paths" object under "compilerOptions".
Gatsby gatsby-node.ts webpack alias configuration
Create a gatsby-node.ts file at the root of your Gatsby project and add the webpack alias configuration using `actions.setWebpackConfig()` to resolve `@/components` to `./src/components` and `@/lib/utils` to `./src/lib/utils`. This allows the app to resolve paths correctly.
Gatsby shadcn/ui Button component usage example
Import the Button component from @/components/ui/button and use it in a React component: `import { Button } from "@/components/ui/button"; export default function Home() { return <div><Button>Click me</Button></div> }`
Gatsby Tailwind CSS v3 note
This Gatsby installation guide is for Gatsby with Tailwind CSS v3. For new projects, shadcn/ui recommends using one of the other frameworks that support Tailwind CSS v4.
shadcn/create tool for setup
shadcn/create allows building a preset visually and generating a framework-specific setup command. This is the recommended approach for new projects. It is available for Next.js, Vite, Laravel, React Router, Astro, and TanStack Start.
Installation methods overview
There are three main installation approaches: using shadcn/create to build and generate a setup command, using the CLI to scaffold directly from the terminal, or adding shadcn/ui to an existing project. Each framework guide includes an Existing Project section with manual setup steps.
Supported frameworks
shadcn/ui supports Next.js, Vite, TanStack Start, Laravel, React Router, Astro, and manual React setup.
Laravel setup prerequisite
For Laravel, the app must be created with laravel new before using shadcn/create or shadcn init.
Install @shadcn/helpers
npm install @shadcn/helpers
Create Laravel app with CLI
To create a new Laravel app, run 'laravel new my-app' from the command line. You will be prompted to choose the React starter kit. After creation, move into the project directory with 'cd my-app'.
Example: Using Switch component in Laravel
Import and use the Switch component in a Laravel page file: ```tsx import { Switch } from "@/components/ui/switch" const MyPage = () => { return ( <div> <Switch /> </div> ) } export default MyPage ``` This example shows how to import the Switch component from the ui folder and use it in a page component.
Laravel setup requires React starter kit
The shadcn CLI does not scaffold a new Laravel app. Start by creating a Laravel app with the React starter kit using 'laravel new my-app', then choose how to configure shadcn/ui. If you already have a Laravel app with React and Inertia configured, you can skip this step.
Next.js installation: three setup paths
There are three ways to install shadcn/ui in Next.js: use shadcn/create to build a preset and generate a project, use the CLI to scaffold a new project directly, or manually configure shadcn/ui in an existing Next.js project.
shadcn/create workflow for Next.js
To use shadcn/create for Next.js: open shadcn/create with template=next to build your preset visually, selecting style, colors, fonts, and icons. Click Create Project and choose your package manager. Copy the generated command which takes the form: npx shadcn@latest init --preset [CODE] --template next. The exact command may include additional options like --base, --monorepo, or --rtl. Then add components with npx shadcn@latest add [component-name]. For monorepo projects, run from apps/web or specify the workspace with -c apps/web.
Import shadcn/ui components in Next.js
Components are imported from @/components/ui/[component-name]. For example: import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card". In a monorepo project, import from @workspace/ui/components/[component-name] instead.
Next.js create-next-app recommended defaults
When creating a new Next.js project with create-next-app, use the recommended defaults to automatically configure Tailwind CSS, the App Router, and the @/* import alias. Run: npx create-next-app@latest. To use a src/ directory, add --src-dir flag or choose Yes when prompted: npx create-next-app@latest --src-dir. With --src-dir, Next.js places the app in src/app and configures the @/* alias to point to ./src/*.
tsconfig.json @/* import alias configuration
Ensure your tsconfig.json includes the @/* import alias under compilerOptions.paths. The configuration should be: { "compilerOptions": { "paths": { "@/*": ["./*"] } } }. If using --src-dir, point the alias to ./src/* instead of ./*.
Manual shadcn/ui setup in existing Next.js project
To add shadcn/ui to an existing Next.js project: ensure Tailwind CSS is installed (refer to the official Next.js installation guide if needed), verify tsconfig.json has the @/* import alias configured, run npx shadcn@latest init to set up shadcn/ui, then add components with npx shadcn@latest add [component-name].
Card component example in Next.js
This example shows how to use the Card component with its subcomponents in a Next.js app: ```tsx import { Card, CardContent, CardDescription, CardHeader, CardTitle, } from "@/components/ui/card" export default function Home() { return ( <Card className="max-w-sm"> <CardHeader> <CardTitle>Project Overview</CardTitle> <CardDescription> Track progress and recent activity for your Next.js app. </CardDescription> </CardHeader> <CardContent> Your design system is ready. Start building your next component. </CardContent> </Card> ) } ```
Button component example in Next.js
This example shows how to import and use the Button component in a Next.js app: ```tsx import { Button } from "@/components/ui/button" export default function Home() { return ( <div className="flex min-h-svh items-center justify-center"> <Button>Click me</Button> </div> ) } ```
Tailwind CSS is required for shadcn/ui
Components are styled using Tailwind CSS. You must install and configure Tailwind CSS in your project before using shadcn/ui. Follow the Tailwind CSS installation instructions from https://tailwindcss.com/docs/installation.
Manual installation dependencies
To manually install shadcn/ui, install these dependencies: npm install shadcn class-variance-authority clsx tailwind-merge lucide-react tw-animate-css
Configure styles in globals.css
Add the following imports to src/styles/globals.css: @import "tailwindcss"; @import "tw-animate-css"; @import "shadcn/tailwind.css"; Then define @custom-variant dark (&:is(.dark *)); and use @theme inline to map Tailwind theme colors and radius values to CSS variables. Define :root with default light theme values using oklch color space, and .dark with dark theme overrides.
Configure import aliases with tsconfig.json paths
Option A for import aliases: in tsconfig.json, set compilerOptions.baseUrl to "." and compilerOptions.paths to {"@/*": [".*"]} to enable @/ import prefix.
Configure import aliases with package.json imports
Option B for import aliases: in package.json, add imports field with mappings like "#components/*": "./src/components/*.tsx", "#lib/*": "./src/lib/*.ts", "#hooks/*": "./src/hooks/*.ts". Then in tsconfig.json, set compilerOptions.moduleResolution to "bundler" and compilerOptions.resolvePackageJsonImports to true.