How to use @apply in Tailwind v4?

Question

Since Tailwind v4 update, all @apply directives have ceased to function.

The docs provide a workaround with @reference but the posted example is vague.

I tried this but it doesn't work:

<style lang="postcss">
// @reference './../../assets/styles/scss/main.scss'; // workaround (incorrect)
@reference "tailwindcss"; // should be sufficient

header {
  @apply bg-neutral-0; // used to work in Tailwind v3
}
(...)
</style>

When I inspect the Header in the browser, it doesn't have assigned any background color.

Edit. I was missing @tailwindcss/vite but some utility classes still don't work. I.e. @apply block works, but @apply bg-neutral-0 doesn't. It throws an error:

19:26:13 [vite] (client) hmr update /src/components/Header.vue?vue&type=style&index=1&lang.postcss (x2)  
Error: Cannot apply unknown utility class `bg-neutral-0`. Are you using CSS modules or similar and missing `@reference`? https://tailwindcss.com/docs/functions-and-directives#reference-directive

rozsazoltan · Accepted Answer · 2025-11-08 20:33:24Z

5

In fact, the primary recommendation from the creator of TailwindCSS is not to use @apply. Instead, use native CSS and achieve the required color codes or values through variables. The main goal of TailwindCSS is to provide styling through inline classes. I only mentioned this because if you don't force local formatting on the header, and instead simply apply bg-neutral-0 to the header element, it will work without issues.

Now, let's deal with @apply. If you use @reference "tailwindcss";, you only have access to the default values, not the ones you defined yourself. To access your own values, such as --color-neutral-0, you need to reference your main CSS file, just like you did in the first line, and this has to be done with a relative reference.

Sass and TailwindCSS v4 don't work together, but can be used separately - How to use with CSS modules (*.module.css and <style>), @reference, @apply

./assets/styles/scss/main.scss

@use "./tailwind.css";

./assets/styles/scss/tailwind.css

@import "tailwindcss";

@theme {
  --color-neutral-0: #111;
}

Header.vue

<style lang="postcss">
@reference "./../../assets/styles/scss/tailwind.css";

header {
  @apply bg-neutral-0;
}
</style>

I fully agree with Wongjn's explanations. If you set it up so that you can reference a CSS file, since TailwindCSS does not officially support Sass, Less, or Stylus preprocessors, the relative reference will solve your problem. However, instead of using a relative reference, I would create a reference to tailwind.css in package.json and use that in @reference. This way, the result will be much cleaner.

Use Vite aliases with TailwindCSS @reference directive

package.json

// package.json
{
  "imports": {
    "#tailwind.css": "./assets/styles/scss/tailwind.css"
  },
}

Header.vue

<style lang="postcss">
@reference "#tailwind.css";

header {
  @apply bg-neutral-0;
}
</style>

edited Nov 8 at 20:33

answered Aug 22 at 17:49

rozsazoltan

18.2k8 gold badges49 silver badges145 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

van_folmert Aug 22 at 18:02

What a mess. I appreciate the help, though. But why do I need to define my theme and values in tailwind.css if I already have it in tailwind.config.cjs?

rozsazoltan Aug 22 at 18:07

Although TailwindCSS v4 prefers a CSS-first configuration, yes, if you have an external configuration file it can also work - just make sure you declare its relative path in the tailwind.css file with @config directive.

rozsazoltan Sep 17 at 12:54

Related: Stop using @apply - Moni

Wongjn · Accepted Answer · 2025-08-22 17:12:14Z

2

The file that you point to @reference must be a CSS file, not a SCSS file. This CSS file should contain @import "tailwindcss"; or similar. The @reference processing is done entirely through Tailwind and it does not understand any other preprocessor syntaxes.

As per the documentation:

Tailwind CSS v4.0 is a full-featured CSS build tool designed for a specific workflow, and is not designed to be used with CSS preprocessors like Sass, Less, or Stylus.

Think of Tailwind CSS itself as your preprocessor — you shouldn't use Tailwind with Sass for the same reason you wouldn't use Sass with Stylus.

As a workaround, you can try having your Tailwind-related CSS in its own CSS file:

@import "tailwindcss";

@theme {
  …
}

And @import/@use that into your main.scss file:

@import "./path/to/subfile.css";

Then, you can do:

<style lang="postcss">
@reference './../../assets/styles/scss/path/to/subfile.css';

header {
  @apply bg-neutral-0;
}
(...)
</style>

Though as mentioned, this is not guaranteed to work as Tailwind does not support usage with Sass.

It is worth mentioning, Adam Wathan (creator of Tailwind) does seem to advocate avoiding @apply:

Instead, you should look at using Tailwind class names directly:

<header class="bg-neutral-0">
  …
</header>

If your project fully encompasses this paradigm, you may find you write little CSS yourself. Thus you would not need Sass at all, simplifying the project setup.

answered Aug 22 at 17:12

Wongjn

27.1k5 gold badges24 silver badges50 bronze badges

2 Comments

van_folmert Aug 22 at 17:19

I was also missing @tailwindcss/vite plugin. But it still doesn't work. I get now Error: Cannot apply unknown utility class bg-neutral-0.

Wongjn Aug 22 at 18:04

The file that you point to @reference must be a CSS file, not a SCSS file. This CSS file should contain @import "tailwindcss"; or similar. The @reference processing is done entirely through Tailwind and it does not understand any other preprocessor syntaxes.

Collectives™ on Stack Overflow

How to use @apply in Tailwind v4?

2 Answers 2

3 Comments

2 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

3 Comments

2 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related