Improve the CSS Grid Lanes description

[captainbrosset]

Description

Update the way that CSS Grid Lanes layout is described in the intro at https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout/Grid_lanes

Motivation

I see 4 problems with the existing description. In particular, with this paragraph:

Grid lanes layout is a layout method where one axis uses a typical strict grid layout, most often columns, and the other uses a stacking algorithm. On the stacking axis, rather than sticking to a strict grid with gaps being left after shorter items, the items in the following row rise up to fill the gaps.

• The word "Masonry" is not mentioned once.

  While that term does not appear in syntax, it is still, by far, the most common way which developers refer to this layout technique. In fact, even the spec says "Grid lanes layout, sometimes also called “masonry layout”". I think it's wrong to omit it completely. Preserving this term is extremely helpful for findability, and for developers to quickly understand what the guide is about.

• The word "row", in "the items in the following row", is very problematic.

  In a column direction grid lanes layout, there are no rows. The user agent does not construct rows. Developers can't style rows. Referring to a bunch of items as being part of a "row" is incorrect and sends the wrong idea to developers learning to use this new layout.

  For illustration, here are 2 grid lanes layouts. The one on the left has items that are sized similarly, with no big differences in height. Items 5 through 8 are therefore arranged in what almost looks like a row, with item 5 in column 1, item 6 in column 2, etc. However, the example on the right shows that this semblance of a "row" doesn't really exist. Items in this second layout are of very different heights, and items 5 through 8 do not get vertically aligned, and are also out of order. Item 5 in column3, item 6 in column 1, item 7 in column 2, item 8 in column 4.

  

• The phrase "rise up" in "the items in the following row rise up to fill the gaps" is also very problematic.

  In a column direction grid lanes layout, items don't rise up. Saying that they do makes it sound like the user agent first creates a strict grid with both columns and rows, and then rises up items within their columns to avoid gaps. Here is an animation illustrating this incorrect rising up of items:

  

  That's not how grid lanes work at all. Instead, the stacking algorithm looks at items one by one, and finds the shortest lane to put the next item in, possibly ending up a criss-cross pattern where items don't follow a logical reading order. Here is an animation showing the difference between the incorrect rise up and what grid lanes actually does. It shows that items don't end up in the same order because the final order depends on the length of each lane:

  

• The description assumes that most grid lanes layouts are in the column direction.

  While that may be true, I don't think we should say the "most often columns" part. Grid lanes layouts can be in a row or column orientation, just as easily.

Related issues and pull requests

This is a follow-up to #45049.

[github-actions]

Preview URLs (1 page)

• /en-US/docs/Web/CSS/Guides/Grid_layout/Grid_lanes

(comment last updated: 2026-08-27 07:16:09)

[alisonmaher]

As an implementer of Grid Lanes in Chromium, I've been closely involved in the specification discussions surrounding this feature, and I agree that the original wording could lead to author confusion and may lead one to interpret grid lanes as the same placement as grid but just more tightly packed. This is not the case, as the placement order inside a track will be widely different than in grid.

+1 to these edits. The updated wording is clearer, more closely matches the spec, and should make it easier for authors who are already familiar with masonry layouts to connect Grid Lanes to that existing concept.

[chrisdavidmills]

Hi, @captainbrosset!

I really like the new wording and think it improves on what was there before; your reasoning for the changes makes sense.

I would suggest swapping the order of the two paragraphs. It would make more sense to first describe what grid lanes layout is, and then provide the familiar de facto term and bricks in a wall comparison to cement understanding further.

[captainbrosset]

Sounds good @chrisdavidmills, let's cement masonry understanding :)

[chrisdavidmills]

LGTM!

[chrisdavidmills]

Sounds good @chrisdavidmills, let's cement masonry understanding :)

These jokes write themselves ;-)