CSS Mastery

Debugging / intermediate

Debugging overflow: find the box that is wider than the viewport

Horizontal overflow is diagnosable when you inspect the widest box instead of adding overflow hidden to the page.

By Andrew J Hughes

The fastest bad fix for horizontal overflow is body { overflow-x: hidden; }. It hides the symptom, can break sticky positioning, and may clip content that users need.

The better workflow is to find the box that is wider than the viewport.

Step 1: Confirm the scroll axis

Open DevTools and inspect the document element. If the layout width is larger than the viewport, there is at least one descendant forcing the width. Do not assume it is the visually obvious element.

Step 2: Outline the layout

Temporarily add an outline during debugging.

* {
  outline: 1px solid rgba(216, 93, 63, 0.35);
}

This is not a production fix. It helps reveal the element crossing the viewport edge.

Step 3: Inspect common causes

Look for:

  • Grid tracks written as 1fr instead of minmax(0, 1fr).
  • Flex items missing min-inline-size: 0.
  • Images or iframes without max-inline-size: 100%.
  • Long unbroken strings in code, URLs, labels, and tables.
  • Decorative elements positioned outside the page flow.

Step 4: Put overflow where it belongs

A code block can scroll horizontally. A whole page usually should not.

pre {
  overflow-x: auto;
}

.content-column {
  min-inline-size: 0;
}

This keeps the page stable while allowing the specific content type to handle its own constraints.

Step 5: Remove the debugging CSS

After the fix, remove outlines and broad overflow rules. Then test at narrow widths with real content. Overflow bugs often return when the next long label or embedded asset arrives, so the fix should address the sizing rule, not just the current string.

References