CSS display contents: remove a layout box with care

When to use it

A case dashboard's rendering layer adds a plain div around two visual cards. On wide screens, those cards should occupy adjacent grid tracks with their neighboring cards. Applying display contents to that presentation-only div lets its children become grid items. The fallback remains readable if the declaration is ignored: the wrapper occupies one grid cell and its children stack inside it. Do not apply the same technique to a list, table, labeled region, or interactive control just to simplify track placement. The removed box cannot paint its own border, padding, or background, so keep those visual treatments on the children or on a real parent. Test keyboard order, screen-reader grouping, forced colors, and responsive stacking. The DOM order stays the same even when the grid makes the children appear beside unrelated cards; preserve a logical reading sequence in HTML.

.case-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 1rem; }
.case-grid__presentation { display: contents; }
.case-grid__card { min-inline-size: 0; border: 1px solid #8ea6b4; padding: 1rem; }

Cost and verification

Removing a box can simplify grid placement, but it may also change sizing, backgrounds, stacking, and accessibility exposure. A visually empty wrapper can still be meaningful in the document if it carries a role, label, or list relationship. Keep this rule on a neutral wrapper whose loss has been reviewed, and verify the accessibility tree rather than assuming the specification's intended behavior matches every deployed browser. The performance difference is unlikely to justify an architectural rewrite by itself. If a component needs its own padding, clipping, or containing block for positioned children, display contents is the wrong tool. A small markup change or nested grid may be clearer.

Common Mistakes

• Do not apply display contents to a semantic list or labeled region without accessibility testing.
• Do not expect the removed wrapper to paint a border or supply padding.
• Do not confuse a removed layout box with removed DOM content.

Connected lessons

• CSS Property Decisions
• CSS display and normal flow: choose a formatting context deliberately
• CSS grid auto-placement: let repeated records fill available tracks
• HTML lists: choose ordered, unordered, or term-description structure