Color scheme

display: contents and Layout Trees

Every CSS layout system, Grid, Flexbox, and the normal flow, only directly controls the immediate children of a container. If you have a wrapper element between the container and the items you want to place, that wrapper becomes a participant in the layout and its children are invisible to the outer grid or flex context. display: contents is a value that removes an element's box from the rendering tree while leaving its children in place, effectively making the wrapper disappear as far as layout is concerned. It is a powerful tool with a genuinely dangerous accessibility footgun you need to understand before using it.

What display: contents Does

Normally, every element generates a box that participates in layout. That box has dimensions, margins, padding, borders, and a background. When you set display: contents on an element, its box is not rendered at all. The element still exists in the DOM. Its children still exist in the DOM. But the element itself contributes no box to the layout tree. The children behave as if they were direct children of the element's parent.

Think of it as the element becoming a transparent pass-through. Its children move up one level in the formatting context without any change to the HTML structure:


        .wrapper {
            display: contents;
            /* padding, margin, background, border — all ignored */
            /* width, height — meaningless, no box exists */
        }
    

The properties that affect the box itself become inert. Padding, margin, borders, backgrounds, and dimensions have no effect because there is no box to apply them to. Properties that are inherited by children, like color, font-size, and line-height, still work because inheritance does not depend on the box.

The Layout Problem It Solves

Imagine a CSS Grid layout where you want a group of items to share the same named area or participate in the same set of tracks as sibling items. Your HTML has a semantic grouping element around some of those items for accessibility or styling reasons, but that wrapper becomes an extra grid item itself, disrupting the track placement you intended.

A common example is a form where related inputs are wrapped in a <fieldset> or a group <div> for semantic reasons. The grid sees the wrapper as one item, not its children individually. The before/after demo below shows this problem and the display: contents solution side by side.

Problem: Wrapper Interrupts the Grid

Without display: contents
Item 1
Item 2
Item 3
Item 4
Item 5
Item 6

The yellow wrapper is a grid item spanning all three columns. Items 4, 5, and 6 are in a nested grid inside it, not in the outer grid.

With display: contents on the wrapper
Item 1
Item 2
Item 3
Item 4
Item 5
Item 6

The wrapper's box is gone. Items 4, 5, and 6 are now direct participants in the outer grid and flow into its tracks naturally.

The Accessibility Problem

This is the part that makes display: contents genuinely dangerous. When you remove an element's box, some browsers also remove the element from the accessibility tree. This means screen readers, voice control tools, and other assistive technologies cannot find the element at all. It does not just become visually invisible; it becomes semantically invisible.

The severity of this bug has varied by browser and has improved over time, but the history is troubling enough that the WHATWG and MDN documentation both warn against using display: contents on certain element types. The highest-risk elements are:

  • Interactive elements: <button>, <a>, <input>, <select>, <textarea>. Applying display: contents to a button can make it completely invisible to assistive technology while still appearing visually on screen.
  • Landmark elements: <header>, <main>, <nav>, <footer>, <aside>, <section>. These carry implicit ARIA roles. Removing their box may strip those roles from the accessibility tree.
  • Elements with explicit ARIA roles or labels: any element carrying role, aria-label, aria-labelledby, or similar attributes. The attributes remain in the DOM but the accessibility tree entry that uses them may be dropped.
Never Apply to Interactive or Landmark Elements

Do not use display: contents on <button>, <a>, any form element, or any HTML landmark element. Even in browsers where current versions handle this correctly, older browser versions in your users' install base may not, and the cost of getting it wrong is that real users with assistive technology cannot interact with your page.

The Focus Problem

Even when the accessibility tree entry survives, removing an element's box causes a related focus problem. When a user tabs to a focusable element, the browser typically scrolls the focused element's box into view and may apply a visible focus ring around it. If the element has no box, neither of those things works reliably. The focus indicator may appear in an unexpected location or not at all.

This is a separate issue from the accessibility tree problem and affects sighted keyboard users who rely on visible focus indicators to navigate. A page where focused elements have no visible ring because their boxes were removed fails WCAG 2.4.11 (Focus Appearance) and is a real accessibility barrier.

When It Is Safe to Use

Despite the risks, display: contents has legitimate uses when applied to the right elements. The safe category is purely structural, non-interactive, non-landmark wrapper elements that have no ARIA attributes and exist only to group children for CSS targeting or semantic grouping that does not carry an accessibility role.

A plain <div> with no role, no ARIA attributes, no interactivity, and no meaningful styling of its own is a reasonable candidate. A <div> that groups a set of grid items purely to keep the HTML organized is the clearest safe case. Before reaching for display: contents, also consider whether the HTML can be restructured instead, since that is always safer:


        /* Safe: a plain structural div with no semantic role */
        .grid-group {
            display: contents;
        }

        /* Unsafe: a button whose box is needed for focus and accessibility */
        .icon-button {
            display: contents; /* do not do this */
        }

        /* Unsafe: a landmark whose implicit role depends on its box */
        nav {
            display: contents; /* do not do this */
        }
    

The other question to ask before using display: contents is whether CSS Subgrid solves the same problem. Subgrid, covered in the named lines reading, lets children of a grid item participate in the outer grid's tracks without removing their parent's box. Subgrid is the more modern, more accessible, and more robust solution for the layout problem display: contents is often used to solve.

Check Before You Ship

If you do use display: contents on any element, test with a screen reader before shipping. VoiceOver on macOS, NVDA on Windows, and TalkBack on Android will reveal whether the element and its children are still announced correctly. If any announcement is missing or the reading order is wrong, do not ship it.

Teaching Video Checklist

When you record your teaching video, make sure your teammates come away understanding these concepts:

  • What display: contents removes from the layout tree and what stays in the DOM
  • A before and after grid demo showing how a wrapper disrupts track placement and how display: contents lets children participate in the outer grid
  • Why box properties such as padding, margin, background, and border have no effect on a display: contents element
  • The accessibility risks: elements dropped from the accessibility tree, broken focus rings, and which element types must never use this value
  • When CSS Subgrid or HTML restructuring is the safer alternative to flattening a wrapper

Start with the side by side grid demo, then inspect the same markup with a screen reader before and after applying display: contents so teammates can hear why this property is dangerous on the wrong element.

Resources