CSS Code style: hiding elements

Good afternoon!
I propose to add a new HTML/CSS Code style recommendation on our HTML and CSS codestyle page, in the WCAG section:

Properly hide elements:

  • Hiding visually and semantically:
    E.g. an element disappearing from the UI after a user interaction.
    • CSS: Use the property and value: display: none.
    • HTML: For inputs only, use the attribute and value: type="hidden".
  • Hiding visually and showing semantically:
    E.g. a label for an interactive element that would just clutter the visual UI.
    • HTML: Use the class: sr-only. (abbreviation of “screen reader only”)
  • Hiding semantically and showing visually:
    {{warning}} This technique should only be used on an element that could be removed without changing the user experience in any other way than the presentation.
    Example of proper usage: The avatar picture to display a ‘User’ entry in a table. It’s always paired with the name of the user, so it’s not an issue to hide it from assistive technologies. In this case it’s better, since the information is repeated in two elements.
    Example of grey area use: A separator in a list. The separator can be seen as nothing but a blank space, but for the user it implies a ‘separation’ between two groups of list elements. This separation should be reflected on a semantic meaning, hiding the separator is not the best solution.
    Example of a clear misuse: Hiding a picture used to illustrate a <p>. Accessible content is content that conveys the same meaning no matter the technology used to read it. The picture has a purpose and meaning, and hiding this from assistive technologies prevents AT users from getting the full experience.
    Use only on leave nodes of the DOM tree because this technique does not hide the content but only the semantics of the node. If you want to hide more than a leaf node, it’s very probable that you should consider hiding it visually too. If it’s still not possible, using the aria-hidden attribute is the last resort.
    • HTML: Use the attribute and value: role="presentation".

Those are obviously not the only possible ways to hide elements, but I figured that if we could be consistent with our practice it would improve code quality. This doesn’t cover all situations, but most of them. Some questions should be asked anyways when using other possible techniques.

I decided to prefer role=presentation over aria-hidden. For me, even if the presentation role is a bit less powerful of a , it does not rely on the aria standards but html ones and therefore will have better support and compatibility.

What do you think of this proposal? Is the wording too heavy or imprecise? Is this an appropriate level of detail for a code style convention or should we make it shorter with details in a child page?
Thanks in advance for your feedback :slight_smile:

Lucas C.


  1. Removal techniques and implications, codepen by Vincent Valentin
  2. Hiding content responsibly by Kitty Giraudel
  3. Hiding semantics with the presentation role (ARIA APG)
  4. Aria-hidden vs display:none, by Scott O’Hara

To me this doesn’t specify how I would actually hide an HTML element that is not an input and doesn’t have a CSS selector to target. Should I use style="display: none"? To me this seems like the worst option of the three equivalent options we have (class="hidden", hidden and style="display: none"). I think I would prefer to use the hidden attribute as it is short and doesn’t depend on CSS styles.

As this mentions labels, I think it should also link to Providing Accessible Names and Descriptions | APG | WAI | W3C to give more information about labeling content.

Apart from that, +1 from my side.

I meant it as a way to enforce using CSS for hidden elements, considering that we already have the CSS codestyle:

  • don’t use inline style declarations

Does that make sense to enforce having a CSS selector to target hidden elements?

If you want to make an element hidden visually and semantically using HTML, you can also consider just removing it from the HTML too :))
I know there’s a fair bit of ‘permanently hidden’ inputs in our source. I’m pretty sure removing them would spell a lot of trouble, that’s why I added a mention about them in the proposal.

The label is only mentioned once in an example. The resource you shared is important and should be linked somewhere in the codestyle practice page, but I’m not sure it would fit in the current proposal.

No, this is important, e.g., for how to hide menus, drawers, … - in most of these cases you want to have them in the source and not add them using, e.g., JavaScript.

Do you mean I should add a new class/id for every element I want to hide and then write new CSS code targeting that selector to hide it? This doesn’t sound good to me.

For menus and drawers, in regards to progressive enhancement, they should be showed by default when JS is unactivated. Else, you would lose all the features they contain, which is IMO not a better alternative than a cluttered visual UI.

For most hidden elements, you want to eventually show them using Javascript later on, and to do so AFAIK you need a selector for that too so having a selector doesn’t sound bad to me.
Moreover, it’s just the parent element since “display: none” (CSS) just like “hidden” (HTML) hides every child.

Why does that sound wrong to you?

XWiki doesn’t use progressive enhancement. It did some time ago but this was dropped.

Yes, true, but JavaScript is more powerful than CSS so you might be able to use something that you cannot use in CSS (yet, CSS is also getting more powerful). Also, I’m still not convinced that it might not be a good idea in the end to fully hide elements that are referenced by aria-describedby to avoid that screen readers read them twice. And in this case, while you will indeed have an id on this element, it will just create useless CSS code to always also write a CSS rule to hide the element.

Because we’re cluttering the code with a huge number of CSS rules that all do the same.

I think it’s still useful to think with it in mind. Just like accessibility, it’s really difficult to perfectly fulfill it, but keeping it in mind goes a long way.

I wouldn’t call it cluttering since I think it’d be less than 5% of rules, and CSS has to be a bit repetitive. The color attribute probably holds more than that and it’s normal… But I get your point. I checked it out and bootstrap has a ‘hidden’ class with one rule → ''display: none !important". We should probably not use it, since ‘hidden’ is just more standard and efficient using HTML or JS.

One point of this codestyle proposal is to limit the amount of ways we use to hide elements, and I thought it would be okay to not hide completely using HTML and favorite using CSS. IMO, we can’t remove the CSS way to hide completely (would need JS to expand on hover…).

Changing the first section to:

  • Hiding visually and semantically:
    E.g. an element disappearing from the UI after a user interaction.
    • CSS: Use the property and value: display: none.
    • HTML:
      • For inputs, use the attribute and value: type="hidden".
      • For others, use the boolean attribute: hidden.

Does that look good to you?

This basically means that from now on we should use the hidden HTML attribute instead of a dedicated CSS class, such as class="hidden". Maybe we should state this more clearly. Otherwise +1 on my side.


Maybe we should state this more clearly.

I’ll add a footnote :+1:

Updated HTML & CSS Code Style - XWiki

1 Like