@headlessui/tailwindcss incompatible to tailwindcss v4

[topical]

What package within Headless UI are you using?

@headlessui/tailwindcss and @headlessui/vue

What version of that package are you using?

@headlessui/tailwindcss v0.2.1 and @headlessui/vue v1.7.23

What browser are you using?

Any

Reproduction URL

Just try to install tailwindcss v4 and @headlessui/tailwindcss:

% npm install -D tailwindcss@4

added 1 package in 175ms
% npm install @headlessui/tailwindcss
npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: undefined@undefined
npm error Found: [email protected]
npm error node_modules/tailwindcss
npm error   dev tailwindcss@"^4.0.3" from the root project
npm error
npm error Could not resolve dependency:
npm error peer tailwindcss@"^3.0" from @headlessui/[email protected]
npm error node_modules/@headlessui/tailwindcss
npm error   @headlessui/tailwindcss@"*" from the root project
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.
npm error
npm error
npm error For a full report see:
npm error /Users/topical/.npm/_logs/2025-02-06T11_18_51_142Z-eresolve-report.txt
npm error A complete log of this run can be found in: /Users/topical/.npm/_logs/2025-02-06T11_18_51_142Z-debug-0.log

Describe your issue

@headlessui/tailwindcss is (officially) incompatible to tailwindcss v4

[mirhamasala]

It’s frustrating to have completed an entire TailwindCSS V4 migration only to discover that neither Headless UI nor the Typography plugin are compatible with TailwindCSS V4. It would be considerate to the users to include a clear notice about this—ideally, right at the top of the upgrade guide. Adding such a note would be simple and would save users a lot of time and frustration. 🙏🏼

[philipp-spiess]

Hey @topical! Thanks for reporting. You're right the version range in the peerDepenendecy for tailwindcss needs to be updated! The plugin, however, should be fully compatible with Tailwind CSS v4 if you force the npm dependency via:

npm install -D tailwindcss@4 --force

@mirhamasala Sorry for the frustration you are having :( I'm curious if you can explain more about the kind of compatibility issues you are referring to regarding the Typography plugin? The npm version dependency range is updated to work with v4 already on that plugin, so I'm surprised you ran into issues there.

[philipp-spiess]

We just published an updated version of @headlessui/tailwindcss that does not have a version conflict anymore when installed with Tailwind CSS v4. Thanks for the bug report!

[mirhamasala]

Thank you, @philipp-spiess.

I'm curious if you can explain more about the kind of compatibility issues you are referring to regarding the Typography plugin?

I encountered similar migration issues as those described in this thread, particularly around customizing the plugin’s theme. In the end, I followed this advice, and it worked. However, having clear official migration documentation would have been really helpful.