CssHow-ToBeginner · 3 min read

How to Use Subgrid in CSS: Syntax and Examples

Use display: subgrid on a nested grid container to inherit the grid lines from its parent grid, allowing child items to align perfectly with the parent grid's rows or columns. This helps create consistent layouts without duplicating grid definitions.

📐

Syntax

The subgrid value is used with the display property on a nested grid container. It inherits the grid tracks (rows or columns) from its parent grid container.

display: grid; creates a new grid container.
display: subgrid; makes the nested grid use the parent's grid lines.
Use grid-template-columns or grid-template-rows with subgrid to specify which axis inherits the parent's tracks.

css

/* Parent grid container */
.parent {
  display: grid;
  grid-template-columns: 100px 100px 100px;
  grid-template-rows: 50px 50px;
  gap: 10px;
}

/* Nested grid using subgrid for columns */
.child {
  display: subgrid;
  grid-template-columns: subgrid;
  grid-template-rows: 50px 50px;
}

💻

Example

This example shows a parent grid with three columns and two rows. The nested grid inside uses display: subgrid for columns, so its items align exactly with the parent's columns.

html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>CSS Subgrid Example</title>
<style>
  .parent {
    display: grid;
    grid-template-columns: 100px 100px 100px;
    grid-template-rows: 50px 50px;
    gap: 10px;
    background: #eee;
    padding: 10px;
  }
  .parent > div {
    background: #8ac;
    color: white;
    display: flex;
    align-items: center;
    justify-content: center;
    font-weight: bold;
  }
  .child {
    display: subgrid;
    grid-template-columns: subgrid;
    grid-template-rows: 25px 25px;
    gap: 5px;
    background: #c88;
    color: white;
  }
  .child > div {
    background: #eaa;
    display: flex;
    align-items: center;
    justify-content: center;
    font-size: 0.8rem;
  }
</style>
</head>
<body>
  <div class="parent">
    <div>Parent 1</div>
    <div>Parent 2</div>
    <div>Parent 3</div>
    <div class="child">
      <div>Child 1</div>
      <div>Child 2</div>
      <div>Child 3</div>
      <div>Child 4</div>
      <div>Child 5</div>
      <div>Child 6</div>
    </div>
    <div>Parent 5</div>
    <div>Parent 6</div>
  </div>
</body>
</html>

Output

A grid with three columns and two rows in light gray background. The fourth cell contains a nested grid with six smaller boxes aligned exactly under the parent's three columns, showing consistent column widths and spacing.

⚠️

Common Pitfalls

Using display: subgrid on a container that is not inside a grid will not work.
Subgrid only inherits tracks on the axis you specify (columns or rows), so forgetting to set grid-template-columns: subgrid; or grid-template-rows: subgrid; means no inheritance.
Browser support for subgrid is limited; check compatibility before using in production.
Trying to use subgrid on both rows and columns simultaneously is valid but can be complex; test carefully.

css

/* Wrong: no parent grid */
.no-parent {
  display: subgrid; /* Has no parent grid to inherit from */
}

/* Right: inside a grid parent */
.parent {
  display: grid;
  grid-template-columns: 100px 100px;
}
.child {
  display: subgrid;
  grid-template-columns: subgrid;
}

📊

Quick Reference

display: subgrid; — Use on nested grid container to inherit parent's grid tracks.
grid-template-columns: subgrid; — Inherit columns from parent grid.
grid-template-rows: subgrid; — Inherit rows from parent grid.
Browser support: Supported in Firefox; limited or no support in Chrome, Safari as of mid-2024.
Use case: Align nested grid items perfectly with parent grid lines for consistent layouts.

✅

Key Takeaways

Use display: subgrid on nested grids to inherit grid tracks from the parent grid.

Specify which axis to inherit with grid-template-columns: subgrid; or grid-template-rows: subgrid;.

Subgrid helps align nested items perfectly with the parent grid's layout.

Ensure the parent container has display: grid for subgrid to work.

Check browser support before using subgrid in production projects.