Subgrid

Intro

subgrid lets you create use a grid that a parent element has created. There are three subgrid classes:

• subgrid-columns: Creates subgrid for columns
• subgrid-rows: Creates subgrid for rows
• subgrid: Creates subgrid for both columns and rows

All of them must be used on children grid items.

By far, the most common use case for subgrid is subgrid-rows, but we’ll start the guide with subgrid-columns because its easier to grasp.

subgrid columns

subrgid-columns lets you use subgrid only for columns. To use subgrid-columns, you must:

1. Use --span to the element with subgrid so it knows the number of columns it should adopt from the parent grid.
2. Use --span to define the number of columns in the grandchild element.

<!-- 4 Column grid -->
<div class="grid-simple [--cols:4]">
  <div>Grid Item</div>

  <!-- Subgrid spans 3 columns -->
  <div class="subgrid [--span:3]">
    <div>Subgrid Item 1</div>
    <div class="[--span:2]">Subgrid Item 2</div>
  </div>
</div>

Subgrid vs display contents

The major differenc is this:

• subgrid creates a “container” that retains the grid structure of the parent element — so rows and columns will be created within this structure.
• display: contents does not create such a container — so it will just use the parent grid.

Here’s an example that shows the difference between them:

<div class="grid-simple [--cols:4]">
  <div>Grid Item</div>

  <!-- Subgrid applied -->
  <div class="subgrid-columns [--span:3]">
    <div>Nested Item 1</div>
    <div class="[--span:2]">Nested Item 2</div>
    <div class="[--span:3]">Nested Item 3</div>
  </div>
</div>

<div class="grid-simple [--cols:4]">
  <div>Grid Item</div>

  <!-- display:contents applied -->
  <div class="contents">
    <div>Nested Item 1</div>
    <div class="[--span:2]">Nested Item 2</div>
    <div class="[--span:3]">Nested Item 3</div>
  </div>
</div>

Nested Subgrid Columns

If you want to nest subgrid-columns in another subgrid, you must do the same thing as before:

1. Use --span to specify the number of columns the nested subgrid column should occupy.
2. Use --span to specify the number of columns the eventual grandchild should specify.

<!-- 5 column grid -->
<div class="grid-simple [--cols:5]">
  <div> Grid Item </div>

  <!-- Outer subgrid spans 4 columns -->
  <div class="subgrid-columns [--span:4]">
    <div> Subgrid Item  </div>

    <!-- Inner subgrid spans 3 columns -->
    <div class="subgrid-columns [--span:3]">
      <div> Inner Subgrid Item 1 </div>
      <div class="[--span:2]"> Inner Subgrid Item 2 </div>
    </div>
  </div>
</div>

Subgrid Rows

subgrid-rows lets you place items within a grid item neatly on a subgrid.

To use subgrid-rows, you must:

1. Use --rowspan to specify the number of rows the subgrid should occupy.
2. Use --rowspan to specify the number of rows the grandchild should occupy.

The easiest way to use subgrid-rows

The easiest way to use subgrid-rows is to structure your HTML such that you --rowspan corresponds to the number of elements in the subgrid.

Here’s the code you need to create the above example.

<div class="grid-simple [--cols:3]">
  <!-- 1st column -->
  <div class="subgrid-rows [--rowspan:3]">
    <div>Title 1</div>
    <div>Short description</div>
    <button>Button</button>
  </div>
</div>

Nested subgrid Rows

If you cannot structure your HTML such that the number of inner items corresponds to the rowspan value, you can create another subgrid-rows and specify the nested --rowspan value.

<div class="grid-simple [--cols:3]">
  <!-- 1st column -->

  <!-- Subgrid with 4 rows -->
  <div class="subgrid-rows [--rowspan:4]">
    <!-- One row -->
    <h3> Title </h3>

    <!-- Two rows -->
    <div class="subgrid-rows [--rowspan:2]">
      <div>Description 1</div>
      <div>Description 2</div>
    </div>

    <!-- One row -->
    <button> Button </button>
  </div>
</div>

Adjusting the nested rowspan

You can adjust the nested --rowspan if you’re building an irregular grid that contains different rows of items in the subgrid. This can be used to create really fancy grids!

<div class="grid-simple [--cols:3]">
  <!-- 1st column -->
  <div class="subgrid-rows [--rowspan:6]">
    <div class="[--rowspan:1]">...</div>
    <div class="[--rowspan:2]">...</div>
    <div class="[--rowspan:3]">...</div>
  </div>

  <!-- 2nd column -->
  <div class="subgrid-rows [--rowspan:6]">
    <div class="[--rowspan:2]">...</div>
    <div class="[--rowspan:2]">...</div>
    <div class="[--rowspan:2]">...</div>
  </div>

  <!-- 3rd column -->
  <div class="subgrid-rows [--rowspan:6]">
    <div class="[--rowspan:3]">...</div>
    <div class="[--rowspan:2]">...</div>
    <div class="[--rowspan:1]">...</div>
  </div>
</div>

Subgrid in both directions

subgrid is the combination of subgrid-columns and subgrid-rows. You’d most probably won’t need to use this. But if you do, follow the instructions above for subgrid-columns and subgrid-rows.

Here’s the CSS for subgrid.

.subgrid-columns {
  display: grid;
  gap: inherit;
  grid-template-columns: subgrid;
  grid-column: var(--colstart, auto) / span var(--span, 1);

  > *:not([class*='subgrid']) {
    grid-column-end: span var(--span, 1);
    max-width: 100%;
  }
}

.subgrid-rows {
  display: grid;
  gap: inherit;
  grid-template-rows: subgrid;
  grid-row: var(--rowstart, auto) / span var(--rowspan, 1);

  > *:not([class*='subgrid']) {
    grid-row-end: span var(--rowspan, 1);
  }
}

.subgrid {
  display: grid;
  gap: inherit;
  grid-template-columns: subgrid;
  grid-template-rows: subgrid;
  grid-column: var(--colstart, auto) / span var(--span, 1);
  grid-row: var(--rowstart, auto) / span var(--rowspan, 1);

  > *:not([class*='subgrid']) {
    grid-column-end: span var(--span, 1);
    grid-row-end: span var(--rowspan, 1);
    max-width: 100%;
  }
}

Subgrid

Modifiers

CSS Variables