Subgrid (Nested Grid Alignment)

subgrid is an incredibly powerful, relatively modern feature of CSS Grid that addresses a key limitation of nested grids: alignment.

When you place a standard Grid Container inside another Grid Container, the inner grid's columns and rows are entirely independent. subgrid allows a nested grid to adopt the track sizing of its immediate parent, ensuring that elements deep within your structure maintain perfect alignment with the parent grid lines.

1. The Alignment Problem Without subgrid

Consider a large page grid with twelve columns. You place a "Card Component" that spans columns 2 through 11. Inside the Card, you want to align a title and an image, but if you use an independent grid inside the card, its columns will start from the card's left edge, ignoring the main page grid.

Before Subgrid: You had to manually match the column sizes or use complex negative margins and calculated widths, which was brittle and unmaintainable.

With Subgrid: The inner grid (the Card) can reuse the track definitions (the column lines) of the outer grid, making everything snap into place.

2. How subgrid Works

subgrid is used as a value for either grid-template-columns or grid-template-rows on a Grid Item that is also defined as a Grid Container.

Step 1: The Parent Grid (The Main Structure)

Define the main grid structure as normal on the top-level container.

styles.css

.main-layout {
  display: grid;
  /* Define 4 named columns */
  grid-template-columns: [start] 1fr [content-start] 3fr [content-end] 1fr [end];
  gap: 1rem;
}

Step 2: The Nested Grid (The Child Item)

1. Make the child element a Grid Container (display: grid).
2. Tell the child to span the columns it needs in the parent grid.
3. Set the inner columns property to subgrid.

styles.css

.card-component {
  /* 1. Placement: Span columns 2 and 3 of the parent */
  grid-column: content-start / content-end; 
  
  /* 2. Declaration: Make it a grid container */
  display: grid;
  
  /* 3. Adoption: Inherit the parent's track sizes for the columns it spans */
  grid-template-columns: subgrid; 
}

3. The Result

The nested .card-component now behaves like its own grid, but its columns are precisely aligned with the parent's column lines that it spans.

If the parent columns 2 and 3 were sized $300\text{px}$ and $600\text{px}$ respectively, the subgrid item would now have two $300\text{px}$ and $600\text{px}$ columns available inside of it.

Placement within the Subgrid

The children of the .card-component can now be placed using grid lines that the parent defined. If the parent's span (columns 2 and 3) includes 3 lines (2, 3, and 4), the subgrid's internal lines are 1, 2, and 3.

styles.css

/* Child of .card-component */
.card-title {
  /* Aligns title to the first column line of the parent's spanned area */
  grid-column: 1 / 2; 
}
.card-content {
  /* Aligns content to span the whole subgrid */
  grid-column: 1 / -1; 
}

4. Use Cases for subgrid

Use Case	Description
Form Layouts	Aligning input labels and fields across different components (e.g., a login form and a shipping address form) to the same underlying column lines.
Card Components	Ensuring that the titles and metadata of multiple cards, each in its own container, align perfectly with the page grid lines, regardless of their intrinsic content size.
Complex Tables	Aligning deeply nested table content with the main column structure of the table wrapper.
Component Libraries	Creating reusable components that can slot into any parent grid system and inherit its structure.

Subgrid on Rows

subgrid works identically on the row axis (grid-template-rows: subgrid;). This is extremely useful for aligning components of different heights. For example, if you have two cards side-by-side, but one has a $100\text{px}$ footnote and the other has a $50\text{px}$ footnote, subgrid can ensure the bottom lines of the main content area align perfectly across both cards.

Interactive Subgrid Demo

This demo shows two containers. The outer container defines two main columns. The inner container (.nested-component) uses subgrid to inherit those track sizes, allowing its children (A, B, C) to align exactly with the parent grid lines.