v4 breakpoint prefix not working with @layer components classes

[CasJam]

This was working in v3. Did I miss some docs about this changing in v4?

What version of Tailwind CSS are you using?

For example: v4.0.6

What build tool (or framework if it abstracts the build tool) are you using?

Seeing this issue in Tailwind Play and all of my tests in various projects.

What version of Node.js are you using?

Whatever Tailwind Play uses.

What browser are you using?

I checked Chrome and Safari.

What operating system are you using?

macOS

Reproduction URL

https://play.tailwindcss.com/CGuICpduPQ

Describe your issue

Define a custom class inside of a layer directive, like this:

@layer components {
  .custom-button {
    @apply py-2 px-4 bg-blue-400 rounded inline-block text-white;
  }
}

Works: The custom works when a breakpoint prefix is not present:

<div class="custom-button">Example</div>

Doesn't work: But does not work once any breakpoint prefix is applied:

<div class="sm:custom-button">Example</div>

[wongjn]

As per the documentation, you use @utility in v4: https://play.tailwindcss.com/GOzBabVMYT?file=css

---

As an aside, Adam Wathan (creator of Tailwind) does seem to advocate avoiding @apply:

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

[philipp-spiess]

Yeah we no longer intercept @layer utilities and @layer components. Here are some clarifications to the upgrade docs that might help: https://github.com/tailwindlabs/tailwindcss.com/pull/2096/files#diff-883ecc2f9d29eec4e9dec095c43239637e42e734d4f01dfbca811a769bb4efab

[CasJam]

I see, thanks @philipp-spiess @wongjn.

I think I found the docs a little unclear on this.

The new @utility directive seems like it's a replacement for using @layer base { ... }, but it's not clear that it should also be a replacement for @layer components { ... }.

Also, I see that this section on using @layer to define custom components (like buttons, dropdowns, etc.) is still in the v4 docs (I assume because @layer mostly still works). But it'd be helpful if there were a note here to say that in v4, breakpoint prefixes won't work when using component classes defined in @layer components (whereas they did work in v3).

[philipp-spiess]

@CasJam Have you had the chance to look at the suggested documentation changes I linked? I'm curious if this makes things clearer for you: https://github.com/tailwindlabs/tailwindcss.com/pull/2096/files?short_path=883ecc2#diff-883ecc2f9d29eec4e9dec095c43239637e42e734d4f01dfbca811a769bb4efab

Yeah @layer components is still in the docs but this refers to standard CSS layers now and no longer the special-implementation we had in v3: https://developer.mozilla.org/en-US/docs/Web/CSS/@layer

[CasJam]

@philipp-spiess yes I think that's an improvement.

[CasJam]

One more question regarding custom components and avoiding using @apply.

My custom components for buttons (with a "primary" variant) used to look like this:

@layer components {
  .btn {
    @apply px-4 py-2 rounded font-medium cursor-pointer text-base inline-flex items-center space-x-2;
  }

  .btn-primary {
    @apply bg-primary-600 dark:bg-primary-500 text-white
           hover:bg-primary-700 dark:hover:bg-primary-600;
  }
}

Rewriting using @utility and no use of @apply:

@utility btn {
  padding: calc(var(--spacing) * 2) calc(var(--spacing) * 4) calc(var(--spacing) * 2) calc(var(--spacing) * 4);
  border-radius: var(--radius-sm);
  font-weight: var(--font-weight-medium);
  cursor: pointer;
  font-size: var(--text-base);
  display: inline-flex;
  align-items: center;
  gap: calc(var(--spacing) * 2);
}

@utility btn-primary {
  background-color: var(--color-primary-600);
  color: var(--color-white);

  @variant hover {
    background-color: var(--color-primary-700);
  }

  @variant dark {
    background-color: var(--color-primary-500);

    @variant hover {
      background-color: var(--color-primary-600);
    }
  }
}

Is this the recommended way to write a frequently used component like a .btn?

Is it good/bad practice to use @variant inside of @utility definitions?

[wongjn]

The recommended way is to leverage your templating system to apply classes directly in the HTML, instead of in CSS. I've heard @variant is OK.

[CasJam]

I use partials/templates for most things, of course.

But there are still small, highly repetitive components that don't make sense there. Button styling being the most common example. It wouldn't make sense to build a template for each individual button in an app.

[wongjn]

If it is highly repetitive, then it makes the most sense to me to convert it to a template component. However, that's just my two-cents, you do you!