The keyword is grid-lanes

After years of debate over syntax and naming, the CSS Working Group has settled on how masonry layout will be expressed in CSS: setting display: grid-lanes on an element activates it.

A series of tall images arranged in five columns.

The decision follows a resolution from a January 31st, 2025 meeting to re-use grid templating and placement properties for masonry layout. Work on masonry predates that by years, with roots in a 2017 CSSWG GitHub thread opened by Rachel Andrew about building a Pinterest-style layout. Andrew argued the behavior felt closer to flexbox than grid, since the solution depends on item sizes, but noted flexbox couldn't fully deliver it because items flow top-to-bottom rather than across rows.

Hacks, rejected proposals, and a long debate

Early workarounds leaned on clever tricks. Tab Atkins-Bittner described a method requiring known item heights: setting the container to grid: auto-flow dense 1px / <column widths here>; and giving each item grid-row: span <pixel height as integer>; — a 50px item becomes grid-row: span 50;. He acknowledged there was no "simple" way to adapt Grid into masonry, since any approach would involve non-trivial edits to the layout algorithm. Andrew also pushed back on creating a fresh mechanism for each new design pattern: "we can't create a brand new value of display for every distinct design pattern."

Other proposals surfaced along the way, including a pair of new flexbox properties, flex-block-count and flex-block-flow, intended to control item grouping (alongside column-count) and flow. That idea was countered with the observation that it still wouldn't handle children of different heights. External inspiration came from David DeSandro's Masonry library, whose author offered the W3C and browser vendors guidance on image loading, spanning items across columns, gap filling, and retaining horizontal order.

The disagreement dragged on. At a November 2024 discussion of the Masonry Syntax Debate thread, Jen Simmons said she was "personally disappointed that we're not making more progress" after five years of argument. With the naming question now resolved, shorthand adjustments for masonry remain under discussion, with little said on the issue so far.

The names that lost

Picking the keyword alone consumed years. Among the candidates considered before grid-lanes:

  • collapsed-grid or grid collapse
  • grid-stack or stacked-grid
  • grid-pack, packed-grid, or grid pack
  • compact-grid or compact grid
  • grid-masonry or masonry-grid
  • grid-flex or flex-grid
  • grid single-axis (masonry) vs. grid dual-axis (normal grid)
  • grid stack (masonry) vs. grid grid (normal grid)
  • staggered-grid or grid staggered
  • uneven-grid
  • semi-grid
  • lane-grid or grid-lanes
  • axial-grid

An outstanding piece: item flow

item-flow remains in the works and is expected to appear only after a proper grid-lanes implementation gains traction. Fantasai has published a hypothetical example of how it might look if added to the spec today, along with an illustration of its use in practice.

item-flow: <item-direction> || <item-wrap> || <item-pack> || <item-slack>

/* shorthand for */
item-direction: row | column | row-reverse | column-reverse
item-wrap: wrap | wrap-reverse
item-pack: normal | dense || collapse
item-slack: <length-percentage>
.masonry {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(14rem, 1fr));
  item-flow: collapse; /* == item-flow: row collapse 1em; */
  gap: 1rem;
}

Browser status

Shipping is the awkward part: every major engine has a masonry implementation behind flags or previews, but each one currently uses an interim syntax and is mid-migration.

  • Chromium 140 shipped masonry as display: masonry in Chrome and Edge; both teams are already moving to grid-lanes, and some Edge demos reflect the change.
  • WebKit implemented masonry in Safari 17 as display: grid; work on grid-lanes appears to be in progress.
  • Mozilla was first, shipping masonry in 2020 using display: grid as well, and is now switching to grid-lanes.

No timeline for full implementation is set. Patrick Brosset maintains a per-browser link pool for tracking progress, and Zell Liew has documented a minimal-JavaScript approach for building masonry layouts today.