Handle `@variant` inside `@custom-variant` #18885

RobinMalfait · 2025-09-04T22:00:30Z

This PR fixes an issue where you cannot use @variant inside a @custom-variant. While you can use @variant in normal CSS, you cannot inside of @custom-variant. Today this silently fails and emits invalid CSS.

@custom-variant dark {
  @variant data-dark {
    @slot;
  }
}

<div class="dark:flex"></div>

Would result in:

.dark\:flex {
  @variant data-dark {
    display: flex;
  }
}

To solve it we have 3 potential solutions:

Consider it user error — but since it generates CSS and you don't really get an error you could be shipping broken CSS unknowingly.
We could try and detect this and not generate CSS for this and potentially show a warning.
We could make it work as expected — which is what this PR does.

Some important notes:

The evaluation of the @custom-variant only happens when you actually need it. That means that @variant inside @custom-variant will always have the implementation of the last definition of that variant.

In other words, if you use @variant hover inside a @custom-variant, and later you override the hover variant, the @custom-variant will use the new implementation.
If you happen to introduce a circular dependency, then an error will be thrown during the build step.

You can consider it a bug fix or a new feature it's a bit of a gray area. But
one thing that is cool about this is that you can ship a plugin that looks like
this:

@custom-variant hocus {
  @variant hover {
    @slot;
  }

  @variant focus {
    @slot;
  }
}

And it will use the implementation of hover and focus that the user has defined. So if they have a custom hover or focus variant it will just work.

By default hocus:underline would generate:

@media (hover: hover) {
  .hocus\:underline:hover {
    text-decoration-line: underline;
  }
}

.hocus\:underline:focus {
  text-decoration-line: underline;
}

But if you have a custom hover variant like:

@custom-variant hover (&:hover);

Then hocus:underline would generate:

.hocus\:underline:hover, .hocus\:underline:focus {
  text-decoration-line: underline;
}

Test plan

Existing tests pass
Added tests with this new functionality handled
Made sure to add a test for circular dependencies + error message
Made sure that if you "fix" the circular dependency (by overriding a variant) that everything is generated as expected.

Fixes: #18524

RobinMalfait · 2025-09-04T22:07:35Z

packages/tailwindcss/src/variants.ts

      name,
      (r) => {
        let body = structuredClone(ast)
+        if (usesAtVariant) substituteAtVariant(body, designSystem)


This is technically evaluated lazily and every time this function is called instead of ahead of time.

But once we compute a variant we cache it anyway so should be fine.

RobinMalfait · 2025-09-04T22:10:28Z

packages/tailwindcss/src/variants.ts

-      {
-        compounds: compoundsForSelectors(selectors),
-      },
+      { compounds: compoundsForSelectors(selectors) },


Custom variants that re-use existing @variants are not compoundable. I had an implementation where the @variant substitution was happening ahead of time to get the selectors out but we have some checks in in-* variant for example that doesn't allow nesting and @variant … is implemented using nesting...

I think this is something we can solve in a separate PR and probably after handling flattening ourselves... can of worms.

This is fine imo. The problem here is the nested style rules are the things that disqualify it because otherwise we'll have to implement flattening ourselves.

Exactly, could be a follow-up PR, but this PR on its own is already an improvement.

RobinMalfait · 2025-09-04T22:14:46Z

packages/tailwindcss/src/index.ts

+  for (let name of customVariants.keys()) {
+    // Pre-register the variant to ensure its position in the variant list is
+    // based on the order we see them in the CSS.
+    designSystem.variants.static(name, () => {})


Open for suggestions here. Like maybe a designSystem.variants.reserve(name) but felt silly to introduce a new method just for this...

But my idea was to have the same behavior as-if you are overwriting internal variants that should maintain the sort order.

There's an argument for keeping the position of the lastly defined @custom-variant because otherwise if you were relying on a library that now introduces a @custom-variant with the same name, the sort order will be different.

i think this is fine. Keeping the last defined one would probably be more CSS-y but it would make overriding builtin variants different from custom ones and I'd prefer that they act the same.

RobinMalfait · 2025-09-05T08:55:46Z

packages/tailwindcss/src/utils/topological-sort.ts

+  let seen = new Set<Key>()
+  let wip = new Set<Key>()
+
+  let sorted: Key[] = []


We could make topologicalSort a Generator which has a nice API, but that's way slower compared to this array-based implementation:

Tested this with a very simple graph:

let graph = new Map<string, Set<string>>([ ['A', new Set(['B', 'C'])], ['B', new Set(['D'])], ['C', new Set(['D'])], ['D', new Set(['E'])], ['E', new Set()], ])

But I don't think the real graphs will be much more complex anyway...

Yeah I'd keep the array in this case. The perf tradeoff makes sense when the memory hit is possibly unbounded but you're likely to hit other perf and memory problems with large CSS files first.

RobinMalfait · 2025-09-05T09:41:59Z

Note: we can likely use the topologicalSort utility when handling @apply, but didn't want to touch that as part of this PR because it might have to change a little bit to get the graph in a shape we can work with.

Might do a follow PR for this.

RobinMalfait · 2025-09-05T10:52:48Z

packages/tailwindcss/src/variants.ts

+    }
+
+    // Update the variant at-rule node, to be the `&` rule node
+    replaceWith(node)


If we never mutate the selector of the & node, then we could skip some layers by using:

Suggested change

replaceWith(node)

replaceWith(node.nodes)

But the final result should be the same. This is also the same behavior we had before so I think we can keep it like this.

thecrypticace · 2025-09-05T11:52:09Z

packages/tailwindcss/src/compat/plugin-api.ts

      // CSS-in-JS object
      else if (typeof variant === 'object') {
-        designSystem.variants.fromAst(name, objectToAst(variant))
+        designSystem.variants.fromAst(name, objectToAst(variant), designSystem)


i kinda wish we didn't have to pass the design system into something hanging off the design system :D

Yeah, one way of solving this is that we put a variantFromAst onto the DesignSystem itself 🤔

or, we can pass in a callback if we want to do something with the ast (body in this case) so the logic lives in the callsite.

I think for now, this is fine because it's all private anyway.

rozsazoltan · 2025-09-06T11:28:40Z

Cool.

RobinMalfait requested a review from a team as a code owner September 4, 2025 22:00

RobinMalfait added 7 commits September 5, 2025 00:01

add failing test

f628ea8

add topological sort utility

0dc5ab5

add substituteAtVariant utility

19949cc

handle @variant inside @custom-variant's

e3b4c4c

use substituteAtVariant in main CSS handling

5f52530

register @custom-variant in the correct topological order

8ef8419

update changelog

6636897

RobinMalfait force-pushed the feat/use-variant-in-custom-variant branch from 828f644 to 6636897 Compare September 4, 2025 22:01

RobinMalfait commented Sep 4, 2025

View reviewed changes

RobinMalfait commented Sep 5, 2025

View reviewed changes

thecrypticace reviewed Sep 5, 2025

View reviewed changes

thecrypticace approved these changes Sep 5, 2025

View reviewed changes

Merge branch 'main' into feat/use-variant-in-custom-variant

866ab4f

RobinMalfait enabled auto-merge (squash) September 5, 2025 12:19

RobinMalfait merged commit 77b3cb5 into main Sep 5, 2025
7 checks passed

RobinMalfait deleted the feat/use-variant-in-custom-variant branch September 5, 2025 12:24

chrisbbreuer mentioned this pull request Oct 20, 2025

chore(deps): update dependency tailwindcss to 4.1.16 stacksjs/headwind#8

Open

1 task

This was referenced Oct 21, 2025

build(deps-dev): Bump tailwindcss from 4.1.13 to 4.1.15 blinklabs-io/utxorpc-example#240

Merged

chore(deps-dev): bump tailwindcss from 3.4.18 to 4.1.16 WhizUs-Labs/kcd-showcase-trw-demo-app#28

Open

Uh oh!

Handle @variant inside @custom-variant #18885

Handle @variant inside @custom-variant #18885

Conversation

RobinMalfait commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RobinMalfait commented Sep 5, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rozsazoltan commented Sep 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Handle `@variant` inside `@custom-variant` #18885

Handle `@variant` inside `@custom-variant` #18885

RobinMalfait commented Sep 4, 2025 •

edited

Loading