Configuration

The components.json file holds configuration for your project. We use it to understand how your project is set up and how to generate components customized for your project.

The components.json file is only required if you're using the CLI to add components to your project. If you're using the copy and paste method, you don't need this file.

You can create a components.json file in your project by running:

npx shadcn@latest init

Style

The style for your components. This cannot be changed after initialization.

{
  "style": "new-york"
}

The default style has been deprecated. Use the new-york style instead.

Tailwind

Configuration to help the CLI understand how Tailwind CSS is set up in your project.

tailwind.config

Path to where your tailwind.config.js file is located. For Tailwind CSS v4, leave this blank.

{
  "tailwind": {
    "config": "tailwind.config.js" | "tailwind.config.ts"
  }
}

tailwind.css

Path to the CSS file that imports Tailwind CSS into your project.

{
  "tailwind": {
    "css": "styles/global.css"
  }
}

tailwind.baseColor

This is used to generate the default theme tokens for your components. This cannot be changed after initialization.

{
  "tailwind": {
    "baseColor": "neutral" | "stone" | "zinc" | "mauve" | "olive" | "mist" | "taupe"
  }
}

tailwind.cssVariables

We use and recommend CSS variables for theming.

Set tailwind.cssVariables to true to generate semantic theme tokens like background, foreground, and primary. Set it to false to generate inline Tailwind color utilities instead.

{
  "tailwind": {
    "cssVariables": true | false
  }
}

This cannot be changed after initialization. To switch between CSS variables and utility classes, you'll have to delete and re-install your components.

tailwind.prefix

The prefix to use for your Tailwind CSS utility classes. Components will be added with this prefix.

{
  "tailwind": {
    "prefix": "tw-"
  }
}

RSC

Whether or not to enable support for React Server Components.

The CLI automatically adds a use client directive to client components when set to true.

{
  "rsc": true | false
}

TSX

Choose between TypeScript or JavaScript components.

Setting this option to false allows components to be added as JavaScript with the .jsx file extension.

{
  "tsx": true | false
}

Aliases

The CLI uses these values and the paths config from your tsconfig.json or jsconfig.json file to place generated components in the correct location.

aliases.utils

Import alias for your utility functions.

{
  "aliases": {
    "utils": "@/lib/utils"
  }
}

aliases.components

Import alias for your components.

{
  "aliases": {
    "components": "@/components"
  }
}

aliases.ui

Import alias for ui components.

{
  "aliases": {
    "ui": "@/app/ui"
  }
}

aliases.lib

Import alias for lib functions.

{
  "aliases": {
    "lib": "@/lib"
  }
}

aliases.hooks

Import alias for hooks.

{
  "aliases": {
    "hooks": "@/hooks"
  }
}

Registries

Configure multiple resource registries for your project.

Basic Configuration

{
  "registries": {
    "@v0": "https://v0.dev/chat/b/{name}",
    "@acme": "https://registry.acme.com/{name}.json"
  }
}

Advanced Configuration with Authentication

{
  "registries": {
    "@private": {
      "url": "https://api.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Tailwind v4

Tailwind v4 brings new features and improvements. Here's how to use shadcn/ui with Tailwind v4.

What's New

• The CLI can now initialize projects with Tailwind v4
• Full support for the new @theme directive and @theme inline option
• All components are updated for Tailwind v4 and React 19
• Removed forwardRefs and adjusted the types
• Every primitive now has a data-slot attribute for styling
• Deprecated the toast component in favor of sonner
• Buttons now use the default cursor
• Deprecated the default style - new projects use new-york
• HSL colors are now converted to OKLCH

Upgrade Your Project

1. Follow the Tailwind v4 Upgrade Guide
2. Update your CSS variables
3. Update colors for charts
4. Use new size-* utility
5. Update your dependencies
6. Remove forwardRef

CSS Variables Update

Move :root and .dark out of the @layer base, wrap color values in hsl(), add the inline option to @theme, and remove the hsl() wrappers from @theme:

: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);
}

Chart Colors Update

Remove the hsl() wrapper from chart colors:

const chartConfig = {
  desktop: {
    label: "Desktop",
-   color: "hsl(var(--chart-1))",
+   color: "var(--chart-1)",
  },
}

Size Utility

Replace w-* h-* with the new size-* utility:

- w-4 h-4
+ size-4

Update Dependencies

pnpm up "@radix-ui/*" cmdk lucide-react recharts tailwind-merge clsx --latest

Remove forwardRef

Replace React.forwardRef<...> with React.ComponentProps<...>, remove ref={ref}, and add a data-slot attribute.

Before

const AccordionItem = React.forwardRef<
  React.ElementRef<typeof AccordionPrimitive.Item>,
  React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Item>
>(({ className, ...props }, ref) => (
  <AccordionPrimitive.Item
    ref={ref}
    className={cn("border-b last:border-b-0", className)}
    {...props}
  />
))
AccordionItem.displayName = "AccordionItem"

After

function AccordionItem({
  className,
  ...props
}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
  return (
    <AccordionPrimitive.Item
      data-slot="accordion-item"
      className={cn("border-b last:border-b-0", className)}
      {...props}
    />
  )
}