v4: Allow @apply to be used with CSS mixins (#19427)

The CSS Custom Functions and Mixins spec [is using `@apply` with dashed
idents](https://drafts.csswg.org/css-mixins-1/#apply-rule) for native
mixin support. We shouldn't attempt to treat these as utilities and try
to compile them since they'll fail.

There one intentional limitation with regards to mixins and our use of
`@apply`: We do not allow users to mix utilities and mixins in the same
at-rule. In other words, all of the following `@apply` rules are
invalid:

```css
.foo {
  /* Invalid because the rules contain both mixins and utilities */
  @apply --my-mixin underline;
  @apply --my-mixin() underline;
  @apply underline --my-mixin;
  @apply underline --my-mixin();
}
```

Aside: Lightning CSS does not yet support this syntax so the results of
a production build won't produce the correct code but we'll at least
handle these correctly in Tailwind CSS itself.

Fixes #19422

---------

Co-authored-by: Robin Malfait <malfait.robin@gmail.com>

Author: thecrypticace

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Remove deprecation warnings by using `Module#registerHooks` instead of `Module#register` on Node 26+ ([#20028](https://github.com/tailwindlabs/tailwindcss/pull/20028))
 - Canonicalization: don't crash when plugin utilities throw for unsupported values ([#20052](https://github.com/tailwindlabs/tailwindcss/pull/20052))
+- Allow `@apply` to be used with CSS mixins ([#19427](https://github.com/tailwindlabs/tailwindcss/pull/19427))
 
 ## [4.3.0] - 2026-05-08
 

packages/tailwindcss/src/apply.ts

@@ -163,13 +163,52 @@ export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
 
       let parts = child.params.split(/(\s+)/g)
       let candidateOffsets: Record<string, number> = {}
+      let normalIdents: string[] = []
+      let dashedIdents: string[] = []
 
       let offset = 0
       for (let [idx, part] of parts.entries()) {
-        if (idx % 2 === 0) candidateOffsets[part] = offset
+        if (idx % 2 === 0) {
+          if (part[0] === '-' && part[1] === '-') {
+            dashedIdents.push(part)
+          } else {
+            normalIdents.push(part)
+          }
+
+          candidateOffsets[part] = offset
+        }
+
         offset += part.length
       }
 
+      if (dashedIdents.length) {
+        // If we have an `@apply` that only consists of dashed idents then the
+        // user is intending to use a CSS mixin:
+        // https://drafts.csswg.org/css-mixins-1/#apply-rule
+        //
+        // These are not considered utilities and need to be emitted literally.
+        if (normalIdents.length === 0) return WalkAction.Skip
+
+        // If we find a dashed ident *here* it means that someone is trying
+        // to use mixins and our `@apply` behavior together.
+        //
+        // This is invalid and the rules must be written separately. Let the
+        // user know they need to move them into a separate rule.
+        let list = dashedIdents.join(' ')
+
+        throw new Error(
+          `You cannot use \`@apply\` with both mixins and utilities. Please move \`@apply ${list}\` into a separate rule.`,
+        )
+      }
+
+      let hasBody = child.nodes.length > 0
+
+      if (hasBody && normalIdents.length) {
+        let list = normalIdents.join(' ')
+
+        throw new Error(`The rule \`@apply ${list}\` must not have a body.`)
+      }
+
       // Replace the `@apply` rule with the actual utility classes
       {
         // Parse the candidates to an AST that we can replace the `@apply` rule

packages/tailwindcss/src/ast.ts

@@ -403,7 +403,8 @@ export function optimizeAst(
         copy.name === '@charset' ||
         copy.name === '@custom-media' ||
         copy.name === '@namespace' ||
-        copy.name === '@import'
+        copy.name === '@import' ||
+        copy.name === '@apply'
       ) {
         parent.push(copy)
       }

packages/tailwindcss/src/index.test.ts

@@ -886,6 +886,100 @@ describe('@apply', () => {
       "
     `)
   })
+
+  it('should be usable with CSS mixins', async () => {
+    let input = css`
+      .foo {
+        /* Utility usage */
+        @apply underline;
+
+        /* CSS mixin usage */
+        @apply --my-mixin-1;
+        @apply --my-mixin-1();
+        @apply --my-mixin-1 --my-mixin-2;
+        @apply --my-mixin-1() --my-mixin-2();
+        @apply --my-mixin-3 {
+          color: red;
+        }
+      }
+    `
+
+    // TODO: once Lightning CSS properly supports it, then we can drop this section:
+    {
+      let compiler = await compile(input)
+      expect(compiler.build([])).toMatchInlineSnapshot(`
+        ".foo {
+          text-decoration-line: underline;
+          @apply --my-mixin-1;
+          @apply --my-mixin-1();
+          @apply --my-mixin-1 --my-mixin-2;
+          @apply --my-mixin-1() --my-mixin-2();
+          @apply --my-mixin-3 {
+            color: red;
+          }
+        }
+        "
+      `)
+    }
+
+    // TODO: this output is currently broken because Lightning CSS doesn't
+    // handle this case correctly yet
+    expect(await compileCss(input)).toMatchInlineSnapshot(`
+      "
+      .foo {
+        text-decoration-line: underline;
+      }
+
+      @apply --my-mixin-1;
+
+      @apply --my-mixin-1();
+
+      @apply --my-mixin-1 --my-mixin-2;
+
+      @apply --my-mixin-1() --my-mixin-2();
+
+      @apply --my-mixin-3 {
+        color: red;
+      }
+      "
+    `)
+  })
+
+  it('should error when trying to use mixins and utilities together', async () => {
+    await expect(
+      compile(css`
+        .foo {
+          @apply underline --my-mixin-1;
+        }
+      `),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: You cannot use \`@apply\` with both mixins and utilities. Please move \`@apply --my-mixin-1\` into a separate rule.]`,
+    )
+
+    await expect(
+      compile(css`
+        .foo {
+          @apply --my-mixin-1 underline;
+        }
+      `),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: You cannot use \`@apply\` with both mixins and utilities. Please move \`@apply --my-mixin-1\` into a separate rule.]`,
+    )
+  })
+
+  it('should error when used with a body', async () => {
+    await expect(
+      compile(css`
+        .foo {
+          @apply underline {
+            color: red;
+          }
+        }
+      `),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: The rule \`@apply underline\` must not have a body.]`,
+    )
+  })
 })
 
 describe('arbitrary variants', () => {

packages/tailwindcss/src/source-maps/source-map.test.ts

@@ -677,6 +677,7 @@ test('@apply generates source maps', async ({ expect }) => {
         color: blue;
         @apply text-[#000] hover:text-[#f00];
         @apply underline;
+        @apply --my-mixin-1 --my-mixin-2();
         color: red;
       }
     `,
@@ -686,29 +687,31 @@ test('@apply generates source maps', async ({ expect }) => {
 
   expect(annotations).toMatchInlineSnapshot(`
     "
-        output.css                                   |    input.css
-                                                     | 
-     1  .foo {                                       | 1  .foo {
-        ^^^^^ A @ 1:0-5                              |    ^^^^^ A @ 1:0-5
-     2    color: blue;                               | 2    color: blue;
-          ^^^^^^^^^^^ B @ 2:2-13                     |      ^^^^^^^^^^^ B @ 2:2-13
-     3    color: #000;                               | 3    @apply text-[#000] hover:text-[#f00];
-          ^^^^^^^^^^^ C @ 3:2-13                     |             ^^^^^^^^^^^ C @ 3:9-20
-     4    &:hover {                                  | 3    @apply text-[#000] hover:text-[#f00];
-          ^^^^^^^^ D @ 4:2-10                        |                         ^^^^^^^^^^^^^^^^^ D @ 3:21-38
-     5      @media (hover: hover) {                  | 
-            ^^^^^^^^^^^^^^^^^^^^^^ D @ 5:4-26        | 
-     6        color: #f00;                           | 
-              ^^^^^^^^^^^ D @ 6:6-17                 | 
-     7      }                                        | 
-     8    }                                          | 
-     9    text-decoration-line: underline;           | 4    @apply underline;
-          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ E @ 9:2-33 |             ^^^^^^^^^ E @ 4:9-18
-    10    color: red;                                | 5    color: red;
-          ^^^^^^^^^^ F @ 10:2-12                     |      ^^^^^^^^^^ F @ 5:2-12
-                                                     | 6  }
-    11  }                                            | 
-    12                                               | 
+        output.css                                       |    input.css
+                                                         | 
+     1  .foo {                                           | 1  .foo {
+        ^^^^^ A @ 1:0-5                                  |    ^^^^^ A @ 1:0-5
+     2    color: blue;                                   | 2    color: blue;
+          ^^^^^^^^^^^ B @ 2:2-13                         |      ^^^^^^^^^^^ B @ 2:2-13
+     3    color: #000;                                   | 3    @apply text-[#000] hover:text-[#f00];
+          ^^^^^^^^^^^ C @ 3:2-13                         |             ^^^^^^^^^^^ C @ 3:9-20
+     4    &:hover {                                      | 3    @apply text-[#000] hover:text-[#f00];
+          ^^^^^^^^ D @ 4:2-10                            |                         ^^^^^^^^^^^^^^^^^ D @ 3:21-38
+     5      @media (hover: hover) {                      | 
+            ^^^^^^^^^^^^^^^^^^^^^^ D @ 5:4-26            | 
+     6        color: #f00;                               | 
+              ^^^^^^^^^^^ D @ 6:6-17                     | 
+     7      }                                            | 
+     8    }                                              | 
+     9    text-decoration-line: underline;               | 4    @apply underline;
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ E @ 9:2-33     |             ^^^^^^^^^ E @ 4:9-18
+    10    @apply --my-mixin-1 --my-mixin-2();            | 5    @apply --my-mixin-1 --my-mixin-2();
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ F @ 10:2-36 |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ F @ 5:2-36
+    11    color: red;                                    | 6    color: red;
+          ^^^^^^^^^^ G @ 11:2-12                         |      ^^^^^^^^^^ G @ 6:2-12
+                                                         | 7  }
+    12  }                                                | 
+    13                                                   | 
     "
   `)
 })