Subgrid

Subgrid lets you use CSS Subgrid easily without the configuration headaches.

Subgrids that are super simple to use — no complexity

No need to define the subgrid on grid-template-columns, grid-template-rows, inheriting gap, and all the configuration nonsense. We do that all for you with the Subgrid class.

<div class="Subgrid">...</div>

/* Properties already created for you */
.Subgrid {
  display: grid;
  grid-template-columns: subgrid;
  grid-template-rows: subgrid;
  grid-column: var(--start, auto) / span var(--span, 1);
  grid-row: var(--rowstart, auto) / span var(--rowspan, 1);
  gap: inherit;

  /* ... and other properties ... */
}

Subgrids in one (or two) directions!

You only need subgrid for one direction most of the time — so we created Subgrid-columns and Subgrid-rows to cater to that use case. But if you need to subgrids in both directions, we’ve got that covered too.

<div class="Subgrid-columns"><!-- Subgrid columns only --></div>
<div class="Subgrid-rows"><!-- Subgrid rows only --></div>
<div class="Subgrid"><!-- Subgrid for both directions --></div>

/* Column-only subgrid */
.Subgrid-columns {
  display: grid;
  grid-template-columns: subgrid;
  grid-column: var(--start, auto) / span var(--span, 1);
  gap: inherit;
  /* ... and other properties ... */
}

/* Row-only subgrid */
.Subgrid-rows {
  display: grid;
  grid-template-rows: subgrid;
  grid-row: var(--rowstart, auto) / span var(--rowspan, 1);
  gap: inherit;
  /* ... and other properties ... */
}

Arrange grid items neatly on both axes

Just use Subgrid-rows and specify the number of elements in the subgrid as the --rowspan variable and everything will be neatly arranged.

<div class="SimpleGrid [--cols:2]">
  <div class="Subgrid-rows [--rowspan:3]">
    <h3>Title</h3>
    <p>Description</p>
    <button>Button</button>
  </div>

  <div class="Subgrid-rows [--rowspan:3]">
    <h3>Title</h3>
    <p>Description</p>
    <button>Button</button>
  </div>
</div>

Title 1

Short description: Lorem ipsum dolor sit.

Title 2

Medium desc: Lorem ipsum dolor, sit amet consectetur adipisicing elit.

Make stuff you can’t do with display: contents

Subgrid-columns let you use the same number of columns, but create multiple rows — while the parent still thinks it’s one!

<div class="SimpleGrid [--cols:4]">
  <div>Grid item</div>
  <div class="Subgrid-columns [--span:3]">
    <div>Nested Item 1</div>
    <div class="[--ispan:2]">Nested Item 2</div>
    <div class="[--ispan:3]">Nested Item 3</div>
  </div>
</div>

Use --ispan to configure the number of columns the grandchild element should occupy.

Subgrid

1 Row

Grid item

Nested Item 1

Nested Item 2

Nested Item 3

Display: Contents

Two rows

Grid item

Nested Item 1

Nested Item 2

Nested Item 3

Want nested subgrids? No problem!

Go crazy and creative and make as many whacky grids as you would like. Subgrid can support them all — and still keep you sane.

This was created with 6 Subgrid rows

Short

Medium

Long

Medium

Long

Medium

Short

This is a pretty complex 10-column grid. It’s created with 2 nested subgrid-column

AG1

AG2

AG4

AG5

AG6

AG7

AG8

AG9

AG10

AG3

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 Subgrid classes are to 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:

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

Both --span and --ispan defaults to 1.

<div class="SimpleGrid [--cols:4]">
  <div>Grid Item</div>
  <div class="Subgrid [--span:3]">
    <div>Subgrid Item 1</div>
    <div class="[--ispan:2]">Subgrid Item 2</div>
  </div>
</div>

Display Contents vs Subgrid-columns

You won’t need Subgrid-columns most of the time because you can just use display: contents on the parent element and --span on the grandchild element. This is easier (and you use lesser keystrokes too).

<div class="SimpleGrid [--cols:4]">
  <div>Item</div>
  <div class="contents">
    <div>Nested item 1</div>
    <div class="[--span:2]">Nested item 2</div>
  </div>
</div>

<div class="SimpleGrid [--cols:4]">
  <div>Grid Item</div>
  <div class="Subgrid [--span:3]">
    <div>Nested Item 1</div>
    <div class="[--ispan:2]">Nested Item 2</div>
  </div>
</div>

You would, however, use Subgrid-columns if you want to create more than 1 row of items in the Subgrid, but retain the whole element as 1 row in the parent grid — this is not doable with display:contents.

If that sounds confusing, the following example may make sense.

<div class="SimpleGrid [--cols:4]">
  <div>Grid Item</div>
  <div class="Subgrid-columns [--span:3]">
    <div>Nested Item 1</div>
    <div class="[--ispan:2]">Nested Item 2</div>
    <div class="[--ispan:3]">Nested Item 3</div>
  </div>
</div>

<div class="SimpleGrid [--cols:4]">
  <div>Grid Item</div>
  <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:

Use --span to specify the number of columns the nested Subgrid column should occupy.
Use --ispan to specify the number of columns the eventual grandchild should specify.

<div class="SimpleGrid [--cols:5]">
  <div> Grid Item </div>
  <div class="Subgrid-columns [--span:4]">
    <div> Subgrid Item  </div>
    <div class="Subgrid-columns [--span:3]">
      <div> Subsub Grid Item 1 </div>
      <div class="[--ispan:2]"> Subsub Grid Item 2 </div>
    </div>
  </div>
</div>

Subgrid Rows

Subgrid-rows is probably the reason most people use CSS Subgrid. It lets you place grand-children elements on the rows of the parent grid — so grandchildren elements can be neatly arranged, like this:

Title 1

Short description, lorem ipsum dolor sit.

Title 2

Medium description, lorem ipsum dolor, sit amet consectetur adipisicing elit.

Title 3

Long description, lorem ipsum dolor sit amet consectetur adipisicing elit. Blanditiis natus tempore quisquam ut consequuntur sunt veniam.

To use Subgrid-rows, you must:

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

Both --rowspan and --irowspan defaults to 1.

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. When you do this, you can omit --irowspan completely.

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

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

  <!-- 2nd column -->
  <div class="Subgrid-rows [--rowspan:3]">
    <div>Title 2</div>
    <div>Medium description</div>
    <button>Button</button>
  </div>

  <!-- 3rd column -->
  <div class="Subgrid-rows [--rowspan:3]">
    <div>Title 3</div>
    <div>Long description</div>
    <button>Button</button>
  </div>
</div>

Nested Subgrid Rows

If you cannot structure your HTML according to the number of elements in --rowspan, the next easiest way is to create another Subgrid-rows and specify the nested --rowspan.

<div class="SimpleGrid [--cols:3]">
  <!-- 1st column -->
  <div class="Subgrid-rows [--rowspan:4]">
    <h3> Title </h3>
    <div class="Subgrid-rows [--rowspan:2]">
      <div>Description 1</div>
      <div>Description 2</div>
    </div>
    <button> Button </button>
  </div>
  <!-- Two more items -->
</div>

Adjusting irowspan

You can adjust --irowspan 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="SimpleGrid [--cols:3]">
  <!-- 1st column -->
  <div class="Subgrid-rows [--rowspan:6]">
    <div class="[--irowspan:1]">...</div>
    <div class="[--irowspan:2]">...</div>
    <div class="[--irowspan:3]">...</div>
  </div>

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

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

Subgrid in both directions

Subgrid lets you create subgrids in both directions — columns and rows. Just heed the above rules of Subgrid-columns and Subgrid-rows and you’re good to go with this.

Please login to view this content

Splendid Labz is free because we love developers and we want to contribute back to the ecosystem.

We only charge for access to the documentation to keep the project going. If you don't wish to pay, feel free to use the content from the features tab, our blogs or our videos as your guide.

Here’s the CSS for Subgrid.

[class*='Subgrid'] {
  display: grid;
  gap: inherit;
}

// Use on the child element of the grid
.Subgrid,
.Subgrid-columns {
  grid-column: var(--start, auto) / span var(--span, 1);
  grid-template-columns: subgrid;

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

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

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

Please login to view this content

Splendid Labz is free because we love developers and we want to contribute back to the ecosystem.

We only charge for access to the documentation to keep the project going. If you don't wish to pay, feel free to use the content from the features tab, our blogs or our videos as your guide.

Subgrid

Modifiers

Class	Description
`Subgrid`	Sets both `grid-template-columns` and `grid-template-rows` to `subgrid` along with other enhancements
`Subgrid-columns`	Sets `grid-template-columns` to `subgrid` along with other enhancements
`Subgrid-rows`	Sets `grid-template-rows` to `subgrid` along with other enhancements

CSS Variables

Variable	Default	Description
`--span`	`1`	Number of columns for the subgrid to span
`--ispan`	`1`	Number of columns for grandchild items to span
`--rowspan`	`1`	Number of rows for the subgrid to span
`--irowspan`	`1`	Number of rows for the grandchild item to span

Please login to view this content

Splendid Labz is free because we love developers and we want to contribute back to the ecosystem.

We only charge for access to the documentation to keep the project going. If you don't wish to pay, feel free to use the content from the features tab, our blogs or our videos as your guide.