tailwindcss: [v4] "hidden" is not the last display utility anymore

What version of Tailwind CSS are you using?

v4.0

Reproduction URL

https://play.tailwindcss.com/1XH8TJa6s3 for v4 (element is shown) https://play.tailwindcss.com/Ajm578zcYz for v3.4.15 (element is not shown)

Describe your issue

The order of the display utilities has slightly changed in v4, putting hidden somewhere in the middle of these utilities by default (after block, but before inline-block or inline-flex), where in v3.4 it was at the end of all the display utilities. I have used TailwindCSS often like this:

<div class="inline-block hidden">Some text that is either displayed as inline-block or hidden</div>

Then I remove or re-add the hidden class with Javascript, which worked fine in v3. In v4 this does not work with inline-block anymore (because inline-block comes after hidden in the generated CSS), while it does work with block (as it comes before hidden). I found the behavior better in v3.4, where hidden was assumed to be the preferred/overriding value (if set) of all the display utilities and comes last in the definitions. I could imagine many people used hidden in this way and will find the new order surprising.

About this issue

  • Original URL
  • State: closed
  • Created 2 years ago
  • Reactions: 9
  • Comments: 24 (4 by maintainers)

Commits related to this issue

Most upvoted comments

Is there any specific reasoning behind this decision? I mean, there are hundreds of millions of projects; do you expect everyone to now rebuild their code structure to match the new order? It seems to me that this is a big breaking change that wasn’t properly addressed in the upgrade guide.

I landed on this comment seeing a similar issue when working in a monorepo (turborepo) with a NextJs 15 app on one side and a UI component library in a shared package. I finally fixed it so here are the issues I bumped into in case anyone else struggles with it:

The problem was that the globals.css file generated by my NextJS app was overriden by the overall styles.css file I had generated and imported from my component library. And since the component library did not include any mobile components, only .hidden style existed and was generated by @import “tailwindcss”.

This page of the Tailwind docs has more information on how to properly ensure that tailwindcss goes through all of the necessary files to generate the final css for the app.

Since I was already generating a style file for my UI library, I had to make sure it was imported PRIOR to tailwindcss going through my app to generate a final CSS file. For me, it looked like adding IN THAT ORDER within my globals.css file: @import "path to my UI CSS file"; @import "tailwindcss"; @import "../../../packages/ui/theme.css";

It also worked when I asked Tailwind to check on both the app and the packages/ui to generate the final globals.css file: @import "tailwindcss" source(none); @source "../app"; @source "../../../packages/ui"; @import "../../../packages/ui/theme.css";

I use Nextjs 15, and hidden even overrides the md:flex, thats well strange! <div className="hidden md:flex">

My work around was to add the exclamation to md:!flex, which is wrong. Am I missing something? Is there a different way to hide an element in v4?

@philipp-spiess Yes, the hidden attribute is a good way to solve it and maybe some additional documentation about it would be helpful (so far I didn’t find anything about it in the docs, it is also not mentioned in the preflight explanation).

It was quite a bit of work though even in my not-so-huge application, so changing the order of the hidden class to come last in the CSS like in v3 would avoid this possible BC break for applications doing something similar without having to do a lot of changes, therefore I still think it would make sense to avoid this pain point for other users upgrading to v4 while also adjusting the docs to promote using the hidden attribute for this kind of behavior from now on.

You shouldn’t ever have two utilities that apply the same CSS property in the same context, because -as you have found - order is not guaranteed. Consider toggling between them.

Furthermore, this pattern was always something that our IntelliSense extension has warned about

Having two display classes on the same element overriding each other is perfectly fine in CSS. It’s not optimal in the same context, so an IntelliSense warning makes sense, but I wouldn’t introduce a breaking change like this because of it. In practice, it’s more likely that hidden is applied in a different context, to a component that already has a base display class, so there will be no warnings:

// renders as `inline-block hidden`, without IntelliSense warning
<Component className={'hidden'} />

function Component({ className, ...rest }) {
    return <div className={classNames('inline-block', className)} {...rest} />;
}

So having hidden last helped with composability. If the breaking change is permanent, perhaps npx @tailwindcss/upgrade should add a note with a workaround for it, so people can either stick with it or make changes and remove it.

@import 'tailwindcss';

/*
  Note on breaking change in Tailwind CSS v4...
*/
.hidden {
   display: none;
}

I have a mobile menu for which i use: (react)

<div className="flex md:hidden">

This makes sure it displays on mobile but hides on larger screens. In tailwind 4 this is no longer working and the mobile menu stays visible across all breakpoints. How should solve this?

Furthermore, this pattern was always something that our IntelliSense extension has warned about:

Can this linter standalone instead of in VSCode? Some of our engineers don’t run VSCode, and it would be great to catch this before hitting production. Running this in CI or as part of our suite of linters would be great.

I feel @finkrer’s issue too.

I have a button component which has inline-flex so it properly positions the elements inside of it. Sometimes I render this button with hidden lg:inline-flex classes added so it’s hidden o mobile, but visible on larger screens.

It’s a common practice and pattern to be able to do that so easily and have hidden be “God” and be the most specific one.

It’s a breaking change which, if it can be refactored, could be reverted easily (famous last words).

Thanks for all your work 🙌

My Button component is inline-flex inside. I used hidden on the component to hide it conditionally. The fact that it is technically the same property… well, let’s just say Tailwind class names, it being inside of the component, and it working just fine made it easy to forget about that.

Now, first, this is a breaking change, and I honestly don’t know where it might pop up where I haven’t noticed it yet.

Second, how do I do this now? Or even, how was I supposed to do it before? The hidden attribute is cool, but what about lg:hidden? Using the Tailwind breakpoints was the whole reason to use hidden the utility class to hide stuff. Do I have to use JS to get the screen width, compare it to a breakpoint, and set the hidden attribute accordingly? Nah, that’s too much work.

I guess from now on it’s lg:hidden!. But if you need to hide for the smaller breakpoint, it’s hidden! lg:block!. Not pretty, still better than JS though.

Really wish this had been included in the upgrade guide. Luckily for us, peer variants still override existing styles when triggered, but we still discovered the hard way that we needed to change a bunch of these over to hidden! or use html hidden attribute when possible.

With any other CSS property I would agree with you, but with hidden it is a convenient way to hide an element that could have any other display utility class at the moment. If you want to toggle, you would need to keep track of the original display class, instead of just being able to add or remove hidden (and not knowing anything about the element itself or how it is being displayed otherwise), so I think being able to add hidden and it coming last in the CSS definitions has some value, and with past TailwindCSS versions this has been the case.

As I am already using v4 for my project, I have “solved” this problem with a zero-width-breakpoint-version of hidden, but as more people switch to v4 I could imagine that this could cause some subtle breaks in applications that assumed the same thing as me and thought Tailwind would keep hidden as the last display utility class.

You shouldn’t ever have two utilities that apply the same CSS property in the same context, because -as you have found - order is not guaranteed. Consider toggling between them.