How to switch to a CSS-first configuration in Tailwind CSS v4 and above

What is the CSS-first configuration

Easier installation, fewer files

It means completely removing the well-known tailwind.config.js file. With Tailwind CSS v4, everything is fully customizable using new syntax directly within your CSS files. This also simplifies the installation process - there's no longer a need for an init step, which is why it's no longer present in v4.

Introduction of separated packages for compatibility with different systems

As a result - and unless you're using the CLI - the CLI has been fully separated from the core package into its own standalone package. To stay consistent with this change, the PostCSS plugin has also been moved to a separate package. Starting with v4, there's even a dedicated Vite plugin, also provided as a new package. You can read more about it here: Tailwind CSS v4: more packages and new Vite support

Syntax

New import, end of @tailwind

The first and most important change is how Tailwind CSS is implemented into your CSS. Previously, you had to include three separate @tailwind directives to add the necessary parts. Now, they've been consolidated, and all you need to do is this:

@tailwind base;@tailwind components;@tailwind utilities;@import "tailwindcss";

This shortens the otherwise more verbose inclusion of the following parts:

@tailwind base;@tailwind components;@tailwind utilities;@layer theme, base, components, utilities;@import "tailwindcss/theme.css" layer(theme);@import "tailwindcss/preflight.css" layer(base);@import "tailwindcss/utilities.css" layer(utilities);

CSS layers

If you're only superficially familiar with CSS, the use of native @import now gives you the opportunity to understand the importance, priority, and application of layers. In CSS, a priority hierarchy can be established between layers - the stronger layer will always override the weaker one.

However, there's one important thing to note: styles not placed inside any layer - so-called unlayered styles - are stronger than all layered styles.

Therefore, starting with v4, it's recommended to place your own custom styles under the base layer, and to make more frequent use of Tailwind CSS's @utility directive.

* { padding: 0;}@layer base { * { padding: 0; }}

• From v4 the reset style cannot be overridden by Tailwind CSS classes

Customize theme

In the tailwind.config.js file, the theme or theme.extend properties were typically used for this purpose. Now that the file has been removed, you need to familiarize yourself with the alternatives.

The following directives collectively replace full theme configuration - meaning you won't be able to solve everything using just @theme.

• Functions and directives

Use the @theme directive primarily to customize core settings - based on the available list of namespaces. Learn more about customizing your theme in the theme variables documentation.

• How to use custom color themes in Tailwind CSS v4

@theme { --font-display: "Satoshi", "sans-serif"; --breakpoint-3xl: 120rem; --color-avocado-100: oklch(0.99 0 0); --color-avocado-200: oklch(0.98 0.04 113.22); --color-avocado-300: oklch(0.94 0.11 115.03); --color-avocado-400: oklch(0.92 0.19 114.08); --color-avocado-500: oklch(0.84 0.18 117.33); --color-avocado-600: oklch(0.53 0.12 118.34); --ease-fluid: cubic-bezier(0.3, 0, 0, 1); --ease-snappy: cubic-bezier(0.2, 0, 0, 1); /* ... */}

You can declare your own variants using @custom-variant. Learn more about adding custom variants in the adding custom variants documentation.

• Specially @custom-variant examples: How to access all the direct children of a div in Tailwind CSS?

@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

<div class="bg-sky-500 theme-midnight:bg-orange-500">...</div>

These variants can then be used within CSS via the Tailwind CSS @variant directive. Learn more using variants in the using variants documentation.

• Tailwind CSS @screen how to use - from v4: @custom-variant and @variant directives
• How can I convert print: and screen: to the new @theme style?

.my-element { background: white; @variant dark { background: black; }}

You can also create new dynamic utilities with @utility. Learn more about registering custom utilities in the adding custom utilities documentation.

• How can overflow-clip-margin be implemented as a utility?

@utility tab-4 { tab-size: 4;}

Plugins

After installing plugins, you can reference them by name using the @plugin directive:

@plugin "@tailwindcss/typography";

If the given plugin supports configuration, you can do it here:

@plugin "daisyui" { themes: light --default, dark --prefersdark; root: ":root"; include: ; exclude: ; prefix: ; logs: true;}

Is tailwind.config.js gone forever?

No. Although from v4 onward it is referred to as the legacy JavaScript-based configuration, implying that sooner or later it will be completely deprecated.

In v4, it is still possible to use it - although it does not fully replace the alternatives mentioned earlier. The theme property can still be used for customization. To do this, you need to use the @config directive and provide the relative path from the current file to your tailwind.config.js file:

@config "../../tailwind.config.js";

Dark mode

In v3, the behavior of dark mode (dark variant) could still be controlled using the dark property. From v4 onward, it is enabled by default based on the browser's prefers-color-scheme. To switch to manual control, you simply need to override the default variant using the @custom-variant directive.

@import "tailwindcss";@custom-variant dark (&:where(.dark, .dark *));

<html class="dark"> <body> <div class="bg-white dark:bg-black"> <!-- ... --> </div> </body></html>

Or with the data-theme attribute:

@import "tailwindcss";@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

<html data-theme="dark"> <body> <div class="bg-white dark:bg-black"> <!-- ... --> </div> </body></html>

I'll leave a few useful links to help you fully master customization:

• Blog: Tailwind CSS v4.0 was released at Janaury 2025
• Docs: Upgrade guide
• Docs: Theme variables