Two syntaxes on the table

The CSSWG draft for masonry doesn't settle the question so much as pose it: grid-integrated syntax or grid-independent syntax. At the time of writing there are two competing proposals, and the disagreement is less about how masonry packs items than about which existing layout model it should grow out of.

Table screenshot from the CSS specification with information on two competing syntaxes for CSS masonry.

What the layout actually does

Masonry behaves like a wall of bricks or stones. Item sizes don't drive the layout — the column does, and less commonly the row. Each item is packed into the nearest column and then adapts to that column's width, so unevenly sized items sit in a column without uneven gaps between them.

Closeup of a slate gray stone wall.

Dave DeSandro's Masonry.js, the tool that stoked the trend around 2010 (and which ran on Beyoncé's website), remains the most widely seen example, reproduced in a CodePen. The layout is also why you'll hear masonry called "Pinterest-style."

Pinterest webpage with a masonry layout of inspirational quotes.

Workarounds have accumulated since. Jhey built a faux version with flexbox, and Chris rounded up others in 2019. None rest on standardized features — columns and flexbox are specced, but not with masonry in mind. Given the layout's long track record, it has a claim on a place in the specs.

How the split happened

The conflict is not new; traces go back to 2020, when Rachel Andrew floated masonry as a sub-feature of grid in Smashing Magazine. By 2022 a masonry editor's draft sat inside CSS Grid Layout Module 3, and Jenn Simmons motioned to advance it to first public working draft. Five days later Chromium engineer Ian Kilpatrick raised two concerns — one about sizing column tracks through grid's layout algorithm, one about accessibility in visual versus reading order.

Grid works by placing everything in the grid ahead of time, then sizing the rows/columns to fit the items. Masonry fundamentally doesn't work this way as you need to size the rows/columns ahead of time – then place items within those rows/columns.

As a result the way the current specification re-uses the grid sizing logic leads to poor results when intrinsically sizing tracks, and if the grid is intrinsically-sized itself (e.g. if its within a grid/flex/table, etc).

That stalled the motion in early 2023. In July of this year Kilpatrick published an alternative path, drawing support from CSS heavyweights including Andrew, who authored the CSS Grid spec. Then, three weeks before this writing, fantasai shared a draft of a separate module written with Tab Atkins, specific to masonry as its own thing.

The argument for display: masonry

Andrew's case rests on defaults. Flexbox starts by putting things in a line and distributing spare space, which is a usable starting point whatever you do next; teaching someone to add space, align items, or switch to a column is a step-by-step walk from those defaults. Grid reaches masonry far less directly — you'd need to add display: grid, then grid-template-columns: <track-listing> (with no way to auto-fill auto tracks, so you pick a count, e.g. grid-template-columns: repeat(3, auto)), then grid-template-rows: masonry. To define rows instead, you move masonry to grid-template-columns and declare rows explicitly. Teaching grid to explain masonry, on this view, lumps two formatting contexts together — another lost entry point into front-end development.

Tyler Sticka, commenting on GitHub Issue #9041, adds that neither flexbox (consistent row sizes, tuned via flex-basis against a percentage of total row width) nor grid (consistent column sizes, with row span set from an expected aspect ratio) feels more intuitive as a foundation. The bigger leap for contributors is properties that significantly change behavior, such as flex-wrap or grid-auto-flow: dense. And @jgotten notes that syntax and semantics can be separated from mechanics: user agents can still reuse grid internals, including subgrids, and make the grid-inside-masonry or masonry-inside-grid relationship explicit.

Speaking for the Chrome team, Andrew cites two intertwined reasons to define masonry outside grid: potential layout performance problems, and the fact that each method has features that make sense in one but not the other.

The argument for folding it into grid

The counterweight is leverage. Kokomi, commenting on Issue #9041, points to subgrid as the key benefit of the grid-integrated route — cohesive designs among child elements are often exactly what masonry wants — and expects future grid enhancements to carry over. Developers could use masonry immediately rather than learning a new system. Angel Ponce puts the tradeoff bluntly: a separate display: masonry prizes potential simplicity at the expense of functionality, and another display type risks confusion and fragmentation. Naman Goel and Ponce also note that masonry gracefully degrades to a traditional grid, and that constrained masonry is already possible in Grid today.

Chris had mild interest in merging the two back in 2020, before the debate sharpened, liking how grid-template-rows: masonry; reads: no rows are being set, there aren't really rows anymore, and so there are none to inherit in subgrid.

What it comes down to is a choice between building on existing CSS layout machinery and the ergonomics of a fresh approach — each with merits and costs, depending on what you prioritize.

Where things stand

The working group is collecting feedback. Andrew, Kilpatrick and Atkins published a joint call for comments eight days before this writing; beyond the ask, it is a solid overview of both proposals and their trade-offs. Feedback goes to GitHub Issue #9041.