How to Configure Tailwind CSS v4 with shadcn Components and the new-york-v4 Style

The shadcn/ui registry automatically detects Tailwind CSS v4 by checking for an empty tailwind.config file and falls back to the "new-york-v4" style, requiring no manual configuration beyond installing Tailwind v4 dependencies.

When migrating to Tailwind CSS v4 in projects using shadcn/ui components, the registry system automatically selects the correct component bundle through intelligent configuration detection. According to the shadcn-ui/ui source code, the CLI inspects your Tailwind configuration to determine version compatibility and seamlessly routes component imports to the new-york-v4 namespace without requiring explicit style overrides.

How the Registry Auto-Detects Tailwind CSS v4

The shadcn/ui CLI uses a fallback mechanism to identify Tailwind v4 projects based on configuration file analysis. In packages/shadcn/src/registry/constants.ts, the system defines FALLBACK_STYLE = "new-york-v4" at line 7, which serves as the default style when Tailwind v4 is detected.

The detection logic resides in packages/shadcn/src/registry/config.ts (lines 1-22). When your project uses the "new-york" style but contains an empty Tailwind configuration file (indicating v4), the registry returns FALLBACK_STYLE instead of the standard style. This occurs because Tailwind CSS v4 typically uses CSS-based configuration rather than JavaScript configuration files, leaving tailwind.config.* files empty or minimal.

The resolver then builds component import paths using this calculated style. As implemented in packages/shadcn/src/registry/resolver.ts at line 98, the system constructs paths as registry/${style}/..., which becomes registry/new-york-v4/... when the fallback activates.

Installing Tailwind CSS v4 and Triggering the new-york-v4 Style

To activate the automatic v4 detection, install Tailwind CSS v4 alongside the Vite plugin:

pnpm add -D tailwindcss@^4.1.0 @tailwindcss/vite

Create a minimal tailwind.config.ts that signals v4 compatibility through its emptiness. The registry interprets a configuration file without custom themes or plugins as a Tailwind v4 project:

// tailwind.config.ts
import { type Config } from "tailwindcss";

export default {
  content: [
    "./src/**/*.{tsx,ts,js,jsx}",
    "./node_modules/@shadcn/ui/**/*.{tsx,ts,js,jsx}",
  ],
  theme: {
    extend: {},
  },
  // Empty configuration signals Tailwind CSS v4 to the registry
} satisfies Config;

Because this configuration contains no custom theme extensions or plugins, the shadcn resolver treats your project as a Tailwind v4 project and automatically selects the new-york-v4 style for all component imports.

Importing Components from the new-york-v4 Registry

Once the registry detects Tailwind v4, component imports resolve automatically to the v4-compatible paths. You can import components using the explicit v4 namespace:

import { Button } from "@/registry/new-york-v4/ui/button";

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

The resolver also supports legacy-style imports and rewrites them dynamically. If you import from @/registry/new-york/ui/button, the system automatically rewrites the path to registry/new-york-v4/ui/button at build-time when Tailwind v4 is detected, ensuring backward compatibility while using the correct component variants.

Adding Components with the shadcn CLI

The shadcn CLI handles Tailwind v4 detection during component installation. When adding a component, the CLI reads your tailwind.config.ts, detects the v4 configuration, and writes files to the correct registry location:

pnpm dlx shadcn-ui@latest add button

This command detects the empty Tailwind configuration, resolves the style to new-york-v4, and installs the component to registry/new-york-v4/ui/button.tsx without requiring additional flags or manual path specification.

Summary

• Automatic detection: The registry checks tailwind.config.* for empty configurations to identify Tailwind CSS v4 projects via the logic in packages/shadcn/src/registry/config.ts.
• Fallback style: packages/shadcn/src/registry/constants.ts defines FALLBACK_STYLE = "new-york-v4" as the default for v4 projects.
• Zero configuration: Leave the style option unset or use "new-york"—the system automatically switches to new-york-v4 based on your Tailwind setup.
• Path resolution: packages/shadcn/src/registry/resolver.ts builds import paths dynamically, routing to registry/new-york-v4/... when v4 is detected.
• CLI support: The shadcn-ui@latest add command automatically detects your Tailwind version and installs components to the correct location.

Frequently Asked Questions

How does shadcn/ui detect that I'm using Tailwind CSS v4?

The CLI inspects your tailwind.config.* file for custom theme extensions or plugins. If the configuration file is essentially empty—containing only default content paths without theme overrides—the registry interprets this as a Tailwind v4 project and activates the new-york-v4 fallback style defined in packages/shadcn/src/registry/config.ts.

Do I need to manually specify the new-york-v4 style in my configuration?

No. You should leave the style option unset or set it to "new-york" in your configuration. The registry automatically resolves to new-york-v4 when it detects an empty Tailwind configuration. Manual specification of the v4 style is unnecessary and may cause resolution errors if the registry logic changes.

Can I use the standard new-york style imports with Tailwind v4?

Yes. The resolver in packages/shadcn/src/registry/resolver.ts automatically rewrites imports from @/registry/new-york/... to @/registry/new-york-v4/... when Tailwind v4 is detected. However, using the explicit new-york-v4 path in your imports ensures clarity and prevents any ambiguity in your source code.

What happens if my tailwind.config file contains custom theme extensions?

If your Tailwind configuration contains custom theme properties or plugins, the registry assumes you are using Tailwind CSS v3 and routes components to the standard new-york style instead of new-york-v4. To use the v4 registry, ensure your configuration file remains minimal, as Tailwind CSS v4 handles customization through CSS rather than JavaScript configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}