Debugging CSS Grid and Subgrid in Chromium DevTools

This article provides a comprehensive overview of the features within the Chromium browser's Elements panel designed to simplify the debugging of complex CSS Grid and Subgrid layouts. By leveraging interactive DOM badges, the visual Grid Editor in the Styles pane, customizable viewport overlays, and the centralized Layout pane, developers can quickly visualize track sizes, grid areas, and inherited subgrid alignments without relying on manual CSS outlines or guesswork.

Interactive DOM Tree Badges

The quickest way to inspect a grid layout in the Elements panel is through the interactive badges located directly in the DOM tree.

  • Grid Badge: Any HTML element with display: grid or display: inline-grid applied will display a pill-shaped grid badge next to it in the DOM tree.
  • Subgrid Badge: Elements that utilize grid-template-columns: subgrid or grid-template-rows: subgrid receive a dedicated subgrid badge.
  • Persistent Overlays: Clicking either badge toggles a persistent visual overlay on the webpage. Unlike standard element highlighting, this overlay remains active even when you select other elements in the DOM tree, allowing you to adjust child elements while still seeing the parent grid structure.

The Layout Pane

Located in the right-hand sidebar of the Elements panel (alongside the Styles and Computed tabs), the Layout pane acts as a control center for all grids and subgrids present on the page.

Managing Multiple Grids

Complex layouts often involve nested grids or subgrids. The Layout pane lists every active grid container on the page. You can check the boxes next to multiple grids and subgrids to view their overlays simultaneously. Next to each listed grid is a color picker, allowing you to assign high-contrast colors to different grids so they are easily distinguishable on the screen.

Overlay Display Settings

The Layout pane provides granular control over what information the visual overlay displays on the viewport:

  • Show line numbers: Displays both positive and negative line numbers, simplifying the placement of items using grid-column and grid-row.
  • Show track sizes: Displays both the authored size (e.g., 1fr, auto, minmax()) and the actual computed pixel value of each row and column.
  • Show area names: Visualizes the names and boundaries defined by the grid-template-areas property directly over the corresponding grid cells.
  • Extend grid lines: Projects the grid lines infinitely to the edges of the viewport, which is useful for verifying if a grid aligns properly with external page elements.

The Visual Grid Editor in the Styles Pane

Remembering the exact syntax and behavior for CSS alignment properties can slow down debugging. The Styles pane eliminates this friction with a built-in visual editor.

When you inspect a grid container, a small grid icon appears next to the display: grid or display: inline-grid declaration in the Styles pane. Clicking this icon opens a popover UI containing visual buttons for:

  • align-content
  • justify-content
  • align-items
  • justify-items

The icons inside this popover dynamically rotate to match the element's current flex-direction or writing-mode, allowing you to click and immediately preview how your grid tracks and items will align.

Debugging Subgrid Inheritance

Subgrids do not define their own tracks; instead, they borrow tracks from their parent grid. Debugging this relationship is straightforward in the Elements panel:

  1. Enable the grid badge on the parent container and the subgrid badge on the child container simultaneously.
  2. Observe how the subgrid overlay snaps into the parent grid's tracks.
  3. Hover over the subgrid in the DOM tree to inspect its specific box model. This reveals how padding, borders, or custom gap properties applied directly to the subgrid shift its internal content relative to the parent's tracks.