[V4] :merge selector broken

[mhornbacher]

What version of Tailwind CSS are you using?

v4.0.0-beta.9

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

Next.js 15.1.4

What version of Node.js are you using?

v22.13.0

What browser are you using?

Chrome

What operating system are you using?

macOS

Reproduction URL

https://github.com/mhornbacher/tailwind-repro

Describe your issue

At a high level:

1. The following issue is triggered when adding any peer- class with hot reloading
2. All peer- classes are always active after a build

Parsing css source code failed
  530 |   }
  531 |   .peer-disabled\:text-purple-500 {
> 532 |     :merge(.peer):where([data-rac])[data-disabled] ~ & {
      |             ^
  533 |       color: var(--color-purple-500);
  534 |     }
  535 |     :merge(.peer):where(:not([data-rac])):disabled ~ & {

'merge' is not recognized as a valid pseudo-class. Did you mean '::merge' (pseudo-element) or is this a typo? at [project]/src/app/globals.css:531:12

The cause for this, as far as I can tell is as follows:

In the documentation for plugins there is a special :merge selector designed for plugins (like react-aria-components in this example) to extend the focus, disabled... selectors, in this case to enable them to be triggered in more complex accessibility scenarios. (see the react-aria implementation for example.

However in Tailwind 4.0 it seems that this selector is not handled by the new lighting CSS compiler. I know its not that common, but many projects rely on this to simplify accessibility development for their team. Which is something I know that the tailwind team cares about as well :)

[dona168lee]

A quick fix could be to either temporarily switch to an older version of Tailwind (v3.x) or manually handle the styles in your custom CSS for now. Keep an eye on updates from Tailwind, as this may be Commonlit com addressed in future releases.

[mhornbacher]

@dona168lee I may well need to revert to 3.0 for this app to be properly accessible however this is still a bug in 4.0 that should be raised and addressed.

[mhornbacher]

Update, now that V4 is released it seems they removed support for this feature (or at least it is now gone from the documentation)

[deebov]

I posted a quick workaround in the related issue in the react-spectrum repo:

adobe/react-spectrum#7661 (comment)

[philipp-spiess]

We're going to ignore rules that contain a :merge(…) selector with the next release since these are used for peer-* and group-* compounds mostly that are now handled automatically.