CSS Grid Layout Module Level 3

1. Introduction

This section is not normative.

Grid Layout is a layout model for CSS that has powerful abilities to control the sizing and positioning of boxes and their contents. Grid Layout is optimized for 2-dimensional layouts: those in which alignment of content is desired in both dimensions.

Although many layouts can be expressed with regular Grid Layout, restricting items into a grid in both axes also makes it impossible to express some common layouts on the Web.

This module defines a layout system that removes that restriction so that items can be placed into Grid-like tracks in just one of the axes, while stacking them one after another in the other axis. Items are placed into the column (or row) with the most remaining space based on the layout size of the items placed so far. This module also extends CSS Grid with this new grid item placement strategy and CSS Box Alignment with new alignment features.

1.1. Background and Motivation

Masonry layout is a common Web design pattern where a number of items—commonly images or short article summaries—are placed one by one into columns in a way that loosely resembles stone masonry. Unlike multi-column layout, where content is placed vertically in the first column until it must spills over to the second column, masonry layout selects a column for each new item such that it is generally closer to the top of the layout than items placed later.

The Pinterest search results page exemplifies this layout:

Here, each item has a different height (depending on the content and the width of the column), and inspecting the DOM reveals (as the visual content itself gives no indication of ordering) that each item has been placed into the column with the smallest height so far.

This layout superficially looks similar to multi-column layout; but it has the advantage that scrolling down will naturally lead to "later" items in the layout (that is, those less relevant in the search results).

It’s not possible to achieve this layout using earlier CSS layout models, unless you know up-front how tall each item will be, or use JavaScript for content measurement or placement.

1.2. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords as their property value. For readability they have not been repeated explicitly.

2. Masonry Layout

Masonry layout can be applied to grid containers by specifying the value masonry for one of its axes. This axis is called the masonry axis, and the other axis is called the grid axis.

The full power of grid layout is available in the grid axis. Line names and track sizes can be specified on the grid container, and grid items can be placed into the tracks and span them using grid-column / grid-row as usual. The box alignment properties work the same as in a regular grid container in the grid axis.

In the masonry axis however, items are laid out one after another using the § 2.3 Masonry Layout Algorithm.

Here’s a masonry layout example demonstrating placed and spanning items:

Subgrid grid items are supported, but subgridding only occurs in the grid container’s grid axis; see § 8 Subgrids for details.

If masonry is specified for both grid-template-columns and grid-template-rows, then the used value for grid-template-columns is none, and thus the inline axis will be the grid axis.

Grid items are formed and blockified exactly the same as in a regular grid container.

All CSS properties work the same as in a regular grid container unless otherwise specified by this specification. For example, order can be used to specify a different layout order for the items.

2.1. Line Name Resolution

Grid item line name resolution works the same as if masonry were replaced with none, i.e. line names are resolved in both axes. The line name resolution works exactly is in CSS Grid.

2.2. Grid Axis Track Sizing

Track sizing works the same as in CSS Grid, except that when considering which items contribute to intrinsic sizes:

• All items explicitly placed in that track contribute, and

• All items without an explicit placement contribute (regardless of whether they are ultimately placed in that track).

In the case of spanning items with no explicit placement, they are assumed to be placed at every possible start position, and contribute accordingly.

Note: This algorithm ensures that each track is at least big enough to accommodate every item that is ultimately placed in it, and does not create dependency cycles between placement and track sizing. However, depending on the variation in sizes, tracks could be larger than necessary: an exact fit is only guaranteed if all items are explicitly placed in the grid axis or all items are the same size (or matching multiples of that size, in the case of spanning items).

2.2.1. repeat(auto-fit)

repeat(auto-fit) behaves as repeat(auto-fill) when the other axis is a masonry axis. The reason for this is that auto-placed items depend on the layout size of their siblings. Removing empty tracks after layout wouldn’t be possible in most cases since it might affect any intrinsic track sizes. Even if all track sizes are definite, the containing block size could change for grid-aligned absolutely-positioned descendants. This makes repeat(auto-fit) impossible to support in a grid container with masonry layout.

2.3. Masonry Layout Algorithm

Items are placed in order-modified document order, but items with a definite placement are placed before items with an indefinite position (as in regular grid layout).

For each of the tracks in the grid axis, keep a running position initialized to zero. First for each item with a definite placement in the grid axis, then for each item with an indefinite placement:

1. If the item has an definite placement in the grid axis, use that placement. Otherwise, resolve its grid axis placement using these substeps:
   1. Starting at the first grid axis line in the implicit grid.
   2. Find the largest running position of the grid axis tracks that the item would span if it were placed at this line, and call this position max_pos.
   3. Increment the line number and repeat step 2 until the item would no longer fit inside the grid.
   4. Pick the line that resulted in the smallest max_pos as the item’s definite placement in the grid axis.
2. Place the item in its grid axis tracks at the maximum of the running positions of the tracks it spans.
3. Calculate the size of the item’s containing block and then layout the item. Then calculate its resulting margin box in the masonry axis. Set the running position of the spanned grid axis tracks to max_pos + margin-box-end + grid-gap.

2.4. The masonry-auto-flow Property

The § 2.3 Masonry Layout Algorithm above can be modified in two ways, using the new masonry-auto-flow property:

First, picking definite items first for placement can be inhibited by specifying the ordered keyword so that a plain order-modified document order is used instead. Second, instead of placing the items in the track(s) with the most remaining space as described above we can place them one after another in the grid axis by specifying the next keyword, for example:

<style>
.grid {
  display: inline-grid;
  grid: masonry / repeat(3, 2ch);
  border: 1px solid;
  masonry-auto-flow: next;
}

item { background: silver }
item:nth-child(2n+1) {
  background: pink;
  height: 4em;
}
</style>

<div class="grid">
  <item>1</item>
  <item>2</item>
  <item>3</item>
  <item>4</item>
</div>

(Without masonry-auto-flow: next, item 4 would be placed below item 2.)

3. Containing Block

The containing block for a grid item participating in masonry layout is formed by its grid area in the grid axis and the grid container's content box in the masonry axis.

4. The Implicit Grid

The implicit grid is formed in the same way as for a regular grid container. However, it’s only used in the grid axis. The flow axis specified by grid-auto-flow is ignored: items are always placed by filling the grid axis. direction:rtl reverses the grid if the inline axis is the grid axis (as usual for a regular grid container) and it makes items flow from right to left if the inline axis is the masonry axis.

Here’s a simple example using direction: rtl in the grid axis:

<style>
  .grid {
    display: inline-grid;
    direction: rtl;
    grid: masonry / repeat(4, 2ch);
    border: 1px solid;
  }

  item { background: silver }
  item:nth-child(2n+1) {
    background: pink;
    height: 4em;
  }
  </style>

<div class="grid">
  <item>1</item>
  <item style="grid-column:span 2">2</item>
  <item>3</item>
  <item>4</item>
</div>

Here’s a simple example using direction: rtl in the masonry axis:

<style>
.grid {
  display: inline-grid;
  direction: rtl;
  width: 10ch;
  column-gap: 1ch;
  grid: repeat(4, 2em) / masonry;
  border: 1px solid;
}

item { background: silver }
item:nth-child(2n+1) {
  background: pink;
  width: 4ch;
}
</style>

<div class="grid">
  <item>1</item>
  <item style="grid-row:span 2">2</item>
  <item>3</item>
  <item>4</item>
</div>

5. Sizing Grid Containers

Sizing Grid Containers works the same as for regular grid containers but with the following addendum for the masonry axis: The max-content size (min-content size) of a grid container in the masonry axis is the largest distance between the grid container’s content-box start edge and the maximum margin-box end of all the items, when sized under a max-content constraint (min-content constraint).

Here’s a simple example:

<style>
.grid {
  display: inline-grid;
  grid: masonry / 50px 100px auto;
  grid-gap: 10px;
  border: 1px solid;
}
item { background: silver; margin: 5px; }
</style>

<div class="grid">
  <item style="border:10px solid">1</item>
  <item>2</item>
  <item>3</item>
  <item style="height:50px">4</item>
  <item>5</item>
  <item>6</item>
</div>

6. Alignment and Spacing

Gutters are supported in both axes. In the masonry axis, the gap is applied between the margin boxes of each pair of adjacent items. Margins do not collapse in either axis.

In the grid axis, alignment works the same as in a regular grid container.

In the masonry axis, content-distribution is applied to the content as a whole, similarly to how it behaves in block containers. More specifically, the alignment subject is the masonry box, which is the area between the content edge of the grid container and the end margin edge of the item that is the furthest away in the masonry axis, as indicated by the dashed border here:

Note that there is only ever one alignment subject for these properties in the masonry axis, so the unique align-content / justify-content values boil down to start, center, end, stretch and baseline alignment. (normal behaves as stretch as usual for grid containers.) In the figure above, the grid container has align-content: start; but if align-content were at its default normal value, then the masonry box would fill the grid container's content box, due to being stretched. Moreover: if the grid items overflowed the grid container's content box in the masonry axis, then the masonry box would be larger than the grid container's content box.

6.1. Baseline Alignment in the Masonry Axis

Item baseline alignment inside the grid axis tracks works as usual for a regular grid container, and the grid container's baseline is determined the same as for a regular grid container in that axis.

Baseline alignment is not supported in the masonry axis. The first baseline set of the grid container in this axis is generated from the alignment baseline of the first grid item in the first occupied track, and the last baseline set from the last grid item placed.

We could support baseline alignment in the first row. Do we want to?

Should the last baseline come from the last lowest item placed instead?

7. Fragmentation

7.1. Fragmentation in the Masonry Axis

Each grid axis track is fragmented independently in the masonry axis. If a grid item is fragmented, or has a forced break before/after it, then the running position for the tracks that it spans in the grid axis are set to the size of the fragmentainer so that no further items will be placed in those tracks. An item that is split into multiple fragments retains its placement in the grid axis for all its fragments. A grid item that is pushed, however, is placed again by the next grid container fragment. Placement continues until all items are placed or pushed to a new fragment.

7.2. Fragmentation in the Grid Axis

Fragmentation in the grid axis with masonry layout in the other axis is also supported. In this case the fragmentation behaves more like in a regular grid container; however, there’s a separate step to determine which grid-axis track each item is placed into, before fragmentation occurs.

8. Subgrids

Masonry layout is supported in subgrids (e.g. grid: subgrid / masonry), and grids that use masonry can have subgrids as children. However, only a parent grid axis can be subgridded in the normal sense. A subgrid axis with a parent masonry axis will behave as masonry, unless the subgrid’s other axis is also masonry in which case it behaves as none (because a grid container can only have one masonry axis). auto-placed subgrids don’t inherit any line names from their parent grid, because that would make the placement of the subgrid's grid items dependent on layout results; but the subgrid’s tracks are still aligned to the parent’s tracks as usual. Here’s a subgrid example:

<style>
.grid {
  display: inline-grid;
  grid: auto auto 100px / masonry;
  align-content: center;
  height: 300px;
  border: 1px solid;
}

.grid > * {
  margin: 5px;
  background: silver;
}
.grid > :nth-child(2n) {
  background: pink;
}

.grid subgrid {
  display: grid;
  grid: subgrid / subgrid;
  grid-row: 2 / span 2;
  grid-gap: 30px;
}
.grid subgrid > * { background: cyan; }
</style>

<div class="grid">
  <item>1</item>
  <item>2</item>
  <item>3</item>
  <subgrid>
    <item style="height:100px">subgrid.1</item>
    <item>sub.2</item>
    <item>s.3</item>
  </subgrid>
  <item>4</item>
  <item>5</item>
  <item style="width: 80px">6</item>
  <item>7</item>
</div>

Note how the subgrid’s first item ("subgrid.1") contributes to the intrinsic size of the 2nd row in the parent grid. This is possible since the subgrid specified a definite placement so we know which tracks it will occupy. Note also that trying to subgrid the parent’s masonry axis results in the subgrid getting masonry layout in its inline axis.

9. Absolute Positioning

Grid-aligned absolute-positioned descendants are supported. In the masonry axis, all grid positions except line 1 are treated as auto. Line 1 in the masonry axis corresponds to the start of the masonry box (which is usually also the start content edge) and auto uses the grid container padding edge as usual. The containing block is the extent of the tracks the item spans in the grid axis and the position of line 1 and the padding edge in the masonry axis.

It might be useful to define a static position in the masonry axis. Maybe it could defined as the max (or min?) current running position of the grid-axis tracks at that point? Or the end of the item before it?

It would also be useful to be able to align the masonry box end edge somehow, but for that we need a way to address the end line in an implicit grid, or could we just use any non-auto line number other than 1 to indicate the end line given that we don’t really have any lines in this axis other than line 1?

10. Performance Notes

In general, masonry layout should have significantly better performance than the equivalent regular (2-axis) grid layout, particularly when the masonry axis is the block axis since the intrinsic sizing of grid rows is typically quite expensive. Any intrinsic track sizing in the grid axis should be cheaper too, because, typically, only a subset of items contribute to the intrinsic sizing in a masonry layout, contrary to a 2-axis grid where all items spanning an intrinsically-sized track contribute. Stretched items do a second layout with the new size (when it actually changed) so this can be costly if there are a huge amount of stretched items that each contains a lot of content. Especially nested stretched masonry layouts should be avoided unless they are small/trivial.

This can be ameliorated by the author by opting out from the stretching on most items though, e.g. specifying align-items:start and then opting in for just a few items with align-self:stretch to let those items fill the masonry axis. (This performance analysis is from a Gecko perspective, but I suspect there’s some truth to it for other layout engines as well.)

11. Graceful Degradation

Typically, a masonry design can be expected to degrade quite nicely in a UA that supports Grid layout but not masonry layout if the grid/grid-template shorthands are avoided and the longhands are used instead. e.g.

grid-template-rows: masonry; /* ignored by UAs that don’t support it */
grid-template-columns: 150px 100px 50px;

12. Acknowledgements

Thanks goes to Cameron McCormack who wrote a masonry layout explainer document (from which I lifted the Background chapter) and presented it to the CSSWG. Thanks also to everyone who provided feedback on the initial proposal for this feature.