Strategies for Using @apply vs. theme()

[Mahrryie]

Hey Team!

I'd like to delve into the thought process behind our choice to use theme() function or @apply, and when each is preferable. While I understand the need for theme() within calc functions for dynamic calculations, like adjusting heights based on theme values, as shown in the example below:

.content-area {
  height: calc(100vh - theme(spacing.12));
}

I'm curious about the considerations that lead us to choose theme() over @apply for styling elements, such as in this example from your documentation - https://tailwindcss.com/docs/functions-and-directives#functions .

.btn-blue {
  background-color: theme(colors.blue.500);
}

Why was theme() chosen here instead of the seemingly viable @apply bg-blue-500 approach?

.btn-blue {
    @apply bg-blue-500;
}

Additionally, do @apply and theme() have different impacts on the bundle size? If so, which one has less impact on the bundle size?

Looking forward to hearing your insights on this, thanks!

[wongjn]

Adam Wathan (creator of Tailwind) does seem to advocate avoiding @apply:

• https://twitter.com/adamwathan/status/1226511611592085504
• https://twitter.com/adamwathan/status/1559250403547652097

[Mahrryie]

@wongjn thank you!
I see that he's only mentioning @apply.

But then again, is it okay?

.btn-blue {
  background-color: theme(colors.blue.500);
}

I see no difference between using this style rule and @apply bg-blue-500;. In my opinion, background-color: theme(colors.blue.500); should be just as bad as @apply in that context.
And I want to either confirm it or (if using theme() is ok) to know what exactly is different between theme() and @apply .

[wongjn]

He does mention theme() a bit:

The theme function is much simpler, much more predictable, and adds that tiny bit of necessary friction to make you ask yourself

Am I extracting this because I need to or because I want to make things "cleaner"?

[adamwathan]

The biggest difference is that @apply is an enormously complicated beast that does a lot more than you think, while theme() is a very simple function that just grabs a value from your theme and dumps it in the spot where you called the function.

Here's an example that has shown up in our issues/discussions a number of times over the years — say you have some custom CSS using @apply in a pretty innocent way like this:

.foo {
  @apply text-red-500;
}

This generates the CSS you'd expect:

.foo {
  color: rgb(239 68 68)
}

Now say somewhere on your site you have some markup like this:

<div>
  <h1>The <span class="text-red-500">absolute best</span> tool for tracking your spending.</h1>
</div>

...and for some reason (people do this, I still don't know why), someone writes this CSS to tweak the span:

@media (min-width: 900px) {
  h1 > .text-red-500 {
    text-decoration: underline
  }
}

You may be surprised to discover that now your simple .foo class that used @apply text-red-500 generates this CSS:

.foo {
  color: rgb(239 68 68)
}

@media (min-width: 900px) {
  h1 > .foo {
    text-decoration: underline
  }
}

This is because that custom CSS someone wrote that targeted the .text-red-500 selector effectively extended the behavior of the text-red-500 utility. So now when you try to @apply text-red-500, Tailwind tries to apply all of that behavior, not just the original behavior the class had.

This is by design, because the whole point of @apply is to be able to do this sort of refactoring:

- <div class="text-red-500 underline bg-black flex">
+ <div class="text-red-500 some-custom-class">

So some-custom-class needs to behave exactly as if all three of the utilities it applies were directly on the element. The only way for that to be true is for @apply to consider every single CSS rule in your stylesheet that includes those selectors.

Said another way, using our previous example:

<div>
  <h1>The <span class="text-red-500">absolute best</span> tool for tracking your spending.</h1>
</div>

@media (min-width: 900px) {
  h1 > .text-red-500 {
    text-decoration: underline
  }
}

...if we create that same .foo class:

.foo {
  @apply text-red-500;
}

...it's expected that the user can do this refactoring and nothing in the browser changes:

  <div>
-   <h1>The <span class="text-red-500">absolute best</span> tool for tracking your spending.</h1>
+   <h1>The <span class="foo">absolute best</span> tool for tracking your spending.</h1>
  </div>

This is why all this CSS ends up being generated:

.foo {
  color: rgb(239 68 68)
}

@media (min-width: 900px) {
  h1 > .foo {
    text-decoration: underline
  }
}

If we didn't generate that CSS, replacing text-red-500 with foo would be unsafe, even though all foo does is @apply text-red-500 — the underline would be missing.

In contrast, using theme() like this:

.foo {
  color: theme(colors.red.500);
}

...always generates this, no matter what:

.foo {
  color: rgb(239 68 68)
}

So @apply can be fine if you understand it and don't do anything weird, but in general I just consider it an extremely complicated feature that is doing a lot more than I think a lot of people realize. In comparison theme() is extremely simple and predictable.

I also just find it unfortunate that people so often do stuff like:

.some-selector {
  @apply flex;
}

...instead of just:

.some-selector {
  display: flex;
}

In this case, there's really no benefit to using @apply at all, because flex is a completely static value — it's not part of your theme or anything like that. To me, doing something like this is just a totally unnecessary, pre-processor dependent, roundabout way of writing something that could have just been written using standard CSS syntax.

It's more terse for sure, especially when dealing with breakpoints, hover states, etc. but to me it's still not worth it, I'd rather just write the properties out by hand — you're already in a CSS file writing CSS anyways.

Hope that helps!

[harrygreen]

I had no idea, but it makes total sense. I’ve been investigating why our daisyUI CSS contains loads of unused classes, and I think this explains it - they use @apply everywhere (eg button.css).
Is it theoretically safe to do a find/replace to theme()?

[agusterodin]

We use @apply almost exclusively in the rare scenarios where abstracting at the CSS level makes the most sense (as opposed to JavaScript const at top of file, inside component, or inside map loop). We don't use theme() at all.

The reason @apply is compelling is the conciseness, universalness, and Prettier auto-ordering that normal Tailwind utilities afford, even inside a plain CSS file. @apply also offers the ability to quickly paste to/from React code when switching abstraction levels. If you are refactoring code, copy and paste Tailwind utilities between CSS and React means you are a lot less likely to break styles versus the tedious process of writing out longhand properties.

Another advantage is that bad properties like display: flexx don't get caught by the compiler, whereas @apply flexx would get caught by the compiler!

Obviously, use extreme caution when dealing with things like group. As far as i'm concerned, the warranty of group and similar pattern breaks when using @apply. I am perfectly fine with this.