How to Inspect and Debug CSS Subgrid in Safari Web Inspector

CSS Grid revolutionised two-dimensional web layouts, but initial specifications limited grid tracks strictly to direct children. Nested elements could not align their internal columns or rows with the overarching parent grid without cumbersome workarounds. The CSS Grid Level 2 specification resolved this limitation with subgrid, enabling child grids to inherit track sizing, line names, and gaps directly from their parent. Safari provides comprehensive built-in developer tools within Web Inspector to visualise subgrid boundaries, inspect inherited track lines, and debug alignment issues across nested components.

Understanding CSS Subgrid Architecture

In standard CSS Grid, declaring display: grid on a nested container establishes an independent coordinate system. By contrast, declaring grid-template-columns: subgrid or grid-template-rows: subgrid instructs the child container to project its internal child items directly into the parent grid tracks:

.parent-grid {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
  gap: 1.5rem;
}

.child-card {
  grid-column: span 3;
  display: grid;
  grid-template-columns: subgrid;
  grid-template-rows: auto auto 1fr;
}

Because the child card spans 3 columns of the parent, its subgridded columns align with mathematical precision against sibling cards and outer boundaries. Safari Web Inspector includes dedicated grid overlays tailored specifically to expose how parent and child tracks interact.

Enabling Web Inspector in Safari

1. Open Safari on macOS and open Settings (Cmd + ,).
2. Navigate to the Advanced tab.
3. Enable the checkbox for Show features for web developers.
4. Right-click on any element on the target page and choose Inspect Element to launch the inspector.

Visualising Subgrid Overlays in the Elements Tree

Safari automatically detects CSS Grid containers and decorates them with interactive badges in the DOM hierarchy:

1. In Web Inspector, switch to the Elements tab.
2. Examine the DOM tree. Elements utilizing standard grid layouts display a blue grid badge.
3. Nested elements that utilize subgrid display a distinctive subgrid badge next to their tag name.
4. Click the subgrid badge to toggle the visual grid overlay directly on the rendered page canvas.
5. Safari renders nested alignment lines: the parent grid lines appear in one colour palette while the subgrid lines appear overlaid in high-contrast accent lines, clearly indicating which tracks are inherited.

Inspecting Tracks in the Layout Sidebar

For detailed structural analysis, Safari provides a dedicated Layout pane:

1. With Web Inspector open, select the Layout tab in the right-hand sidebar.
2. Locate the Grid Overlays section.
3. You will see a hierarchy listing both the parent grid container and its child subgrids.
4. Configure individual overlay settings:
   • Show line numbers: Displays positive and negative index numbers along both axes.
   • Show line names: Visualises custom line names defined on parent tracks that pass into the subgrid.
   • Show track sizes: Displays computed pixel and fractional values for each track.
   • Show area names: Exposes named grid areas spanning across boundaries.
5. Adjust overlay colours using the colour picker next to each container to distinguish deeply nested subgrid layers.

Debugging Common Subgrid Layout Issues

• Mismatched Span Dimensions: If subgrid tracks appear missing, check the grid-column or grid-row span on the subgridded container. If an element specifies grid-template-columns: subgrid but only spans 1 column of the parent, only a single track is available to its children.
• Overridden Gaps: By default, a subgrid inherits the parent container’s gap properties. However, you can declare a custom gap or column-gap on the child container. Safari’s Layout panel visualises custom gaps as distinct striped diagonal zones within the overlay.
• Implicit Subgrid Tracks: CSS subgrids cannot generate implicit tracks beyond the span allocated from the parent grid. If items overflow the designated span, Safari’s Layout tab flags them as overflowing items in the console and style tree.

Best Practice Tips for Modern Responsive Grids

• Card Alignment: Use grid-template-rows: subgrid across card-based layouts to align card titles, summary descriptions, and call-to-action buttons across cards of varying text lengths.
• Named Line Inheritance: Define semantic line names on the parent (e.g., [content-start], [content-end]) and reference them directly within child subgrid selectors for intuitive maintenance.