Debugging Flexbox & Grid in DevTools

Flexbox and Grid problems are notoriously hard to reason about from CSS alone — "why did this item wrap," "why is this track bigger than I sized it," "why won't align-items center this" are all questions the DevTools layout inspectors answer visually, in seconds, without adding a single debug style to your code.

The flex/grid badges

Any element with display: flex, inline-flex, grid, or inline-grid gets a small colored badge next to it in the Elements panel — "flex" or "grid." Clicking the badge toggles a visual overlay directly on the rendered page.

The badge appears right after the opening tag in the Elements panel tree
Clicking it toggles the overlay on/off for that specific container
A small colored square next to the badge indicates the overlay's color, useful when multiple flex/grid containers are visible at once

The overlay toggles

Overlay element	What it shows
Container outline	The bounds of the flex/grid container itself
Item outlines	The bounds of each individual flex/grid item
Track/line numbers (grid only)	Numbered grid lines along rows and columns
Gap highlighting	Shaded regions showing the `gap` between tracks/items
Main/cross axis arrows (flex only)	Direction indicators for `flex-direction`

Multiple overlays at once

Both Chrome and Firefox support enabling overlays for several flex/grid containers simultaneously, each in a different color, from the Layout pane — useful for comparing a nested grid inside a flex parent without toggling back and forth.

The Flexbox inspector panel

Select a flex container in the Elements panel
Open the Layout tab in the sidebar (Chrome/Edge) or the Flexbox section (Firefox)
Toggle the overlay checkbox to visualize the container on the page
Use the alignment editor buttons to live-preview different justify-content / align-items values without editing CSS

CSS

.toolbar {
  display: flex;
  justify-content: space-between; /* try the alignment editor buttons
                                       in DevTools to preview center,
                                       flex-start, space-around, etc.
                                       live, before committing to one */
  align-items: center;
  gap: 12px;
}

The alignment editor is a genuine time-saver

Instead of editing justify-content in the Styles pane, reloading your mental model, and repeating, the Flexbox panel's alignment buttons apply each value live to the actual page — click through all of them in a few seconds to find the one that looks right, then set that value in your source file.

The Grid inspector panel

Grid debugging benefits even more from visual tools, since track sizing (fr units, minmax(), auto-fit) is genuinely hard to compute by eye.

Line numbers overlay directly on the page, matching the numbers you would use in grid-column: 2 / 4
Named grid lines/areas (from grid-template-areas) are shown by name instead of number when defined
Track sizes are shown next to each row/column — useful for confirming what 1fr or minmax(200px, 1fr) actually resolved to in pixels
A "gap" toggle shades the actual gap regions so you can distinguish gap from track padding

CSS

.dashboard {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: 20px;
}
/* The Grid overlay shows the ACTUAL resolved pixel width of each
   auto-fit column, which is otherwise impossible to know just by
   reading the CSS since it depends on the container's current width */

Debugging gap and track sizing

minmax() and auto-fit results are not visible in source

A declaration like repeat(auto-fit, minmax(200px, 1fr)) tells you the rule for computing column widths, but not the actual resulting pixel widths at the current viewport size — that computation only happens at render time. The Grid overlay is the only reliable way to see the real numbers without doing the math yourself.

Enable the grid overlay for the container in question
Toggle on line numbers and track sizes in the Layout panel options
Resize the viewport (or the DevTools device toolbar) and watch the track widths update live, confirming the responsive behavior actually works as intended
If a gap looks wrong, toggle the gap highlight to distinguish real gap space from a track that is simply wider than expected

Common flex/grid debugging scenarios

Symptom	What to check in DevTools
Item does not wrap when expected	Confirm `flex-wrap: wrap` is actually set — check the Computed panel, not just the badge
Grid item appears in the wrong cell	Enable line numbers overlay and compare against the `grid-column`/`grid-row` values in Styles
align-items: center has no visible effect	Check the container's cross-axis size — a container with no defined height/cross-size has nothing to center within
Gap looks bigger/smaller than the declared value	Toggle the gap overlay; verify no child margins are stacking on top of the gap
Auto-fit columns collapse unexpectedly	Check the resolved track widths shown by the overlay against the container's actual current width

Debugging subgrid

Subgrid inherits its parent's tracks, which makes it especially useful to visualize — the DevTools grid overlay draws both the parent grid's lines and the subgrid's inherited lines, so you can confirm the subgrid is actually aligning to the parent rather than defining its own independent tracks.

CSS

.gallery {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  grid-template-rows: auto auto;
}

.gallery-item {
  display: grid;
  grid-row: span 2;
  grid-template-rows: subgrid; /* inherits the parent's row tracks */
}

Confirming subgrid actually applied

If a browser does not support subgrid, the value is simply invalid and ignored, silently falling back to the item's own independent grid — which looks similar but does not align rows across siblings. Enable the grid overlay on both the parent and the item; if the inherited lines do not appear, subgrid did not take effect.

flex-basis vs width — which one actually won

A flex item's final main-axis size can come from width, flex-basis, or the flex shorthand's basis component — and when more than one is set, it is easy to misjudge which is in effect. The Computed panel settles it by showing the item's actual resolved size directly.

CSS

.item {
  width: 200px;
  flex-basis: 150px; /* flex-basis wins over width on the main axis
                         when both are set and flex-basis isn't auto */
}

Checking it in DevTools

Select the flex item, open Computed, and look at the actual rendered width in the box model diagram — that is the true resolved size, regardless of which declared property is "supposed" to win by spec rule.

Visualizing the order property

order changes visual position without changing DOM position, which is exactly the kind of mismatch DevTools overlays make obvious — the Elements panel tree still shows the original DOM order, while the on-page overlay shows the item positioned according to its order value.

CSS

.item-a { order: 2; }
.item-b { order: 1; } /* renders visually before .item-a despite coming
                          after it in the DOM */

Visual order vs DOM/tab order

Reordering visually with order does not change keyboard tab order or screen-reader reading order, which still follow the DOM. A mismatch between what a sighted mouse user experiences and what a keyboard/screen-reader user experiences is an accessibility bug — verify both, not just the visual layout, when using order.

Go back to the fundamentals these tools visualize in Flexbox vs Grid — when to use each.