What Is CSS Masonry?
Items of different heights get packed into parallel lanes, and shorter items leave no gaps beneath them.
In the W3C editor’s draft of CSS Grid Layout Module Level 3 (21 October 2026), the official name is grid lanes layout. Masonry layout and waterfall layout are listed as alternative names.
Unlike a regular grid layout, rows do not line up across lanes. Each item drops into whichever lane has the most room left.
The draft’s reference example is the Pinterest search results page, where every card has a different height. Earlier CSS could not produce that layout unless item heights were known up front or JavaScript measured them, the draft states.
Masonry, waterfall and brick layouts
Masonry is the umbrella term and usually implies columns. Waterfall means the same thing in practice, with lanes as columns and items stacking downward. Brick flips the direction: lanes become rows and items run left to right.
The spec’s own name, grid lanes, covers both directions.
How the syntax changed
Mozilla’s team wrote the original Grid Level 3 draft in 2019 and 2020, and the feature reached Firefox Nightly in very early 2020, according to WebKit’s January 2026 post. Chrome’s team later argued for a separate display value instead.
| Proposal | Syntax | Status |
|---|
| Mozilla (2019 to 2020) | grid-template-rows: masonry | On by default only in Firefox Nightly, removed in Firefox 159 (27 October 2026) |
| Chrome team | display: masonry with masonry-template-tracks (the Chrome and Edge 140 flagged build reuses grid-template-* and adds masonry-direction) | Alternative proposal, not used by the current draft |
| WebKit and CSS Working Group | display: grid-lanes | In the Level 3 draft, shipped in Safari 26.4 |
Tutorials built on grid-template-rows: masonry or display: masonry describe syntax that no browser ships unflagged. Worth knowing before you copy anything from an older post.
How Does CSS Masonry Place Each Item?
Each item goes into the lane that is currently least filled, taken in DOM order.
The W3C draft keeps a running position for every lane. For each item, the browser picks the lane where it would sit highest, then advances that lane by the item’s height plus the gap.
Multi-column layout and wrapped flex columns fill the first column to the bottom before spilling into the second, so reading order runs down each column.
Grid lanes picks a lane for every new item instead. Earlier items stay nearer the top, and scrolling down reaches later items.
Flow-tolerance and tie-breaking
The default tie threshold is 1em. Lanes within 1em of the shortest one count as equal, and the browser takes the first tied lane after the previous item, so placement keeps moving forward.
At zero tolerance, WebKit’s highway drawing places the second group of items as 7, 5, 6. With a tolerance of half an item height, the groups read 1 to 4, then 5 to 7.
Setting the value to normal resolves to 1em in grid lanes and 0 in every other layout mode, while a length or percentage sets your own tie distance. Infinite gives strict source order and ignores lane lengths entirely.
The draft warns that infinite can put consecutive items far apart vertically. It suggests a large finite value such as 10em or 50vh instead.
WebKit’s introductory post (19 December 2025) adds the keyboard side. A value too high makes focus jump up and down the layout, and one too low makes it jump sideways more than needed.
The property has been renamed along the way. It was item-tolerance in Safari Technology Preview 234, the CSS Working Group renamed it flow-tolerance on 7 January 2026, and Safari 26.4 shipped that name. A later CSSWG rename made it fit-tolerance, which the 21 October 2026 editor’s draft lists and Safari 27.2 (26 October 2026) uses, keeping flow-tolerance as a deprecated alias for now.
Check which name your target browser accepts before shipping, or declare both.
Writing a Masonry Layout with display: grid-lanes
A basic masonry layout is a grid-lanes container with columns defined and a gap. That’s all it takes.
.gallery {
display: grid-lanes;
grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
gap: 16px;
}
That is the example from WebKit’s introductory post, and the steps below unpack it.
- Place all items as direct children of one container. Only direct children become lane items.
- Set
display: grid-lanes on that container. Use inline-grid-lanes when the container should be inline-level. - Define the lanes with
grid-template-columns. The repeat(auto-fill, minmax(250px, 1fr)) value makes columns at least 250px wide and lets the browser decide how many fit. - Add
gap. One value spaces both the lanes and the items inside each lane.
Because the browser sets the lane count from the container width, the layout needs no breakpoints written with media queries, WebKit notes.
Switching to a brick layout
Define rows instead of columns and the lanes run horizontally.
.gallery {
display: grid-lanes;
grid-template-rows: 1fr 1fr 1fr;
}
The browser reads the direction from whichever template you wrote. The orientation property’s initial value, normal, makes that call.
Define both templates and columns win, per the draft. Rows only become the lane axis when grid-template-columns is none.
The property that will control orientation explicitly is still undecided in the 21 October 2026 draft. The options on the table are reusing grid-auto-flow or adding a new property such as grid-lanes-direction. Since normal stays the initial value either way, nothing here blocks you from writing layouts today.
If a layout refuses to flip, check that grid-template-columns is none.
Lane Sizing, Spanning and Explicit Placement
Lane sizes work like track sizes in CSS Grid, so fixed lengths, fr units, minmax() and repeat() all apply.
Since auto-fill derives the lane count from the container width, the layout follows the viewport without extra rules. That covers most responsive design needs.
Varying lane sizes
The everyday choice is repeat(auto-fill, minmax(250px, 1fr)), which gives equal lanes at least 250px wide.
If you want the first and last lanes to stay narrow while the lane count changes, repeat(auto-fill, minmax(8rem, 1fr) minmax(16rem, 2fr)) minmax(8rem, 1fr) does that.
Lanes sized to their content work too. WebKit’s demo uses repeat(auto-fill, minmax(max-content, 24ch)) for a footer mega menu.
Level 3 relaxes repeat() so auto-fill accepts tracks with no definite size, which the max-content pattern above relies on.
One documented constraint applies to intrinsic lanes. Auto-placed items contribute to the size of every lane, not only the one they land in, so a single wide item widens each content-sized lane. The draft guarantees an exact fit only when all items are the same size or all are placed explicitly.
Spanning items
WebKit’s newspaper demo spans the first teaser across 4 lanes and teasers 2 to 8 across 2 lanes, but only above a viewport width of 1250px. To do the same, set grid-column: span n on the item and the others pack around it.
Spanning has a documented failure mode. A spanner that does not fit in the remaining empty lanes drops into the first lane where it fits, and later single-lane items rise above it, breaking the natural reading order (W3C draft).
The draft suggests a tolerance large enough to ignore tiny height differences, and placing related items explicitly so they stay grouped. It also says to avoid mixing span sizes with very uneven item heights.
Explicit placement
An item with a definite lane position goes exactly there, and auto-placed items flow around it. WebKit’s museum demo pins the site header to the last two lanes with grid-column: -3 / -1, whatever the lane count.
Placement works along the lane axis only. The grid-column-* and grid-row-* properties position items across lanes, while the position within a lane is always decided by the browser.
Which Browsers Support CSS Masonry?
Only Safari supports CSS masonry without a flag, starting with Safari 26.4 on macOS and iOS (released 24 March 2026).
Chrome, Edge and Firefox keep it behind flags, according to the Can I Use table read on 27 October 2026.
Safari 26.4 and later covers Safari on iOS 26.4 and later too (WebKit, 24 March 2026). Global usage sits at 12.49% (Can I Use, checked 27 October 2026).
Chrome and Edge have it disabled by default from version 140, with the flagged build announced in July 2025. Firefox kept the earlier syntax behind a flag from version 77, and Firefox 159 replaced it with display: grid-lanes, still off by default outside Nightly.
Treat the usage share as a dated snapshot and recheck it before sizing a fallback.
Chrome, Edge and Firefox
WebKit wrote in January 2026 that Edge, Chrome and Firefox had all made significant progress, so arrival would come sooner than expected. As of October 2026, none of them has taken the feature out of its flag.
Chromium engineers at Edge were moving their flagged build to the finalized syntax in January, and by late June 2026 published demos already ran on display: grid-lanes with the Chrome or Edge flag on (Manuel Matuzović, 24 June 2026). Current Chromium source also parses fit-tolerance, still as an experimental feature.
Firefox changed course this autumn. WebKit’s January 2026 guidance still told Firefox testers to use the original grid-template-*: masonry syntax, but Firefox 159 (27 October 2026) removed that syntax. It now parses display: grid-lanes behind the layout.css.display-grid-lanes.enabled preference in about:config, on by default only in Nightly, and fit-tolerance parsing landed in Firefox 160 builds.
Until the flags come off, cross-browser compatibility decides how you can use it. Treat it as an enhancement, never as the only layout.
Shipping Masonry Today with a Fallback
Safari 26.4 gets lanes. Everyone else gets either a plain CSS Grid layout or a JavaScript library, and WebKit’s January 2026 guidance covers both.
Grid lanes over a CSS Grid base
Declare display twice. Browsers that do not recognize grid-lanes discard the second declaration and keep grid.
.gallery {
display: grid;
display: grid-lanes;
grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
gap: 1lh;
}
The W3C draft shows the same pattern and notes the fallback has more vertical gaps under shorter items.
WebKit adds an @supports not (display: grid-lanes) block that crops every image to a square with aspect-ratio and object-fit: cover, limits headlines to one line and teasers to three lines. The result looks tidy, but the cropped and truncated content is simply missing, as WebKit’s own side-by-side comparison shows.
Accept the gaps for editorial cards where cropping changes meaning. Crop for product tiles where a uniform shape is the design anyway.
JavaScript only where lanes are missing
if (!CSS.supports('display', 'grid-lanes')) {
/* load the library here */
}
CSS.supports returns false in browsers without grid-lanes, so that check decides whether to pull in masonry-layout. Keep the native rules inside @supports (display: grid-lanes) and give other browsers the item margins the library needs.
Structured this way, the library code can sit untouched until every browser supports lanes, and users on supporting browsers never download it.
Testing both paths
The Grid Inspector in Safari 26.4’s Web Inspector overlays order numbers on grid lanes items, so you can see the placement sequence.
Open the page in a browser without support as well, since WebKit recommends confirming that the JavaScript path lays out correctly there.
Choosing a Masonry Technique
Default to grid-lanes with a fallback. Column-count is fine when item order does not matter, and a library only earns its place when the layout has to filter or sort.
Smashing Magazine’s May 2025 survey of workarounds covered manual row-span hacks and CSS columns alongside JavaScript libraries. The table sets those against grid-lanes.
| Technique | Item order | JavaScript needed | Main failure mode |
|---|
| grid-lanes | DOM order, placed across lanes | No | Safari 26.4 and later only |
| CSS multi-column (column-count) | Down each column | No | Cards split across columns without break-inside: avoid |
| Flexbox column wrap | Down each column | No | Wraps only when the container height is constrained |
| CSS Grid with row spans | DOM order | Usually | Spans hand-tuned to item heights |
| JS library (Masonry, Isotope) | DOM order | Yes | Overlap when media loads late; Isotope is paid for commercial work |
When column-count is enough
No JavaScript is needed and every browser handles it. Adding break-inside: avoid keeps a card from splitting between columns (MDN).
The downside is order. Items fill each column top to bottom, so tab order runs down the first column before the second.
WebKit points out the two layouts look alike but differ in tab order, scanability and user experience. Column-count suits image walls where nobody cares which tile is first.
When a JavaScript library still wins
A library still wins when the layout must filter or sort items.
Masonry places items by available vertical space using JavaScript, and Isotope adds sorting and filtering on top, according to David DeSandro’s documentation.
Masonry is MIT-licensed. Isotope needs a purchased license for commercial projects, though open-source use is free.
Both libraries share a quirk. Items overlap when images, web fonts or embedded buttons change size after layout, and the fix is to run layout again once media has loaded, for example with imagesLoaded.
When CSS Masonry Does Not Fit
Skip masonry when the order of items carries meaning. Leaderboards, step lists and timelines depend on sequence, and a lane-by-lane layout hides that sequence. A single column or a regular grid keeps it.
It’s also a poor fit when item heights barely differ. A plain responsive grid is simpler and works everywhere, so masonry earns its cost only when heights vary widely.
Late-loading media is the other risk. Heights drive placement, so an image that loads late can move the items placed after it. Reserve space with aspect-ratio or width and height attributes.
If design sign-off requires identical rendering in every browser, masonry also fails that test, because only Safari 26.4 and later draws the lanes layout.
Source order, focus order and reading-flow
Grid lanes leaves DOM order untouched, so a keyboard user tabs in source order while the eye reads lane by lane.
WCAG 2.2 Success Criterion 2.4.3 Focus Order (Level A) requires focus to follow an order that preserves meaning and operability. The W3C’s Understanding document, says focus order does not have to match the visual layout but should reinforce the reading order the layout implies.
That is the baseline tier of web accessibility conformance. The same document lists making the DOM order match the visual order as a sufficient technique, and lanes bend that match by design.
The W3C draft points to reading-flow as the remedy for items without an inherent order. The property sets the order in which flex or grid items reach speech and focus navigation, and web-features lists it in Chrome 137 (27 May 2025) and Edge 137 (29 May 2025) but not in Firefox or Safari.
That leaves a gap. Safari ships grid lanes without reading-flow. Chrome and Edge ship reading-flow, but grid lanes sits behind a flag there, and as of June 2026 reading-flow did not yet apply to grid lanes containers (Manuel Matuzović).
No browser has both working together.
CSS Masonry FAQ
When will Chrome and Firefox ship CSS masonry?
Neither browser has published a stable release date in the sources checked as of 27 October 2026. WebKit’s January 2026 guidance points readers to Chrome Status for Chromium updates, and Edge engineers were moving the flagged build to the finalized syntax.
How does CSS masonry handle infinite scroll?
Appended items continue in the shortest lane, in DOM order, so the browser needs no JavaScript layout step. WebKit’s introductory post says a page can keep loading content as the user scrolls.
Your script still fetches and inserts the new items.
Can I use CSS masonry in WordPress?
Yes, anywhere that accepts CSS, such as a theme stylesheet or the Customizer’s Additional CSS panel.
Browser support limits stay the same, so wrap the rules in @supports (display: grid-lanes) and keep a base layout for other browsers.
Is subgrid supported in a masonry layout?
Yes, but only along the lane axis, according to the W3C draft of 21 October 2026.
Subgridding the stacking axis converts the nested grid into a lanes container instead.
Does the order property work in CSS masonry?
Yes. The W3C draft says all properties behave as in a regular grid container unless stated otherwise, so order sets a different layout order.
The same reordering and accessibility caveats as in grid and flex apply.
Moving from a JavaScript Library to CSS Masonry
A JavaScript masonry library moves to CSS masonry safely as a fallback, not a deletion. Lanes go first, and the library loads only where display: grid-lanes is missing.
Audit the items whose position carries meaning before anything else, because source order is the one change a screenshot will not reveal. After that, gate the library behind a feature check and test in Safari 26.4 and one unsupported browser.
The price is two layout paths in one codebase, which means two paths to test on every release.
Delete the library once Chrome, Edge and Firefox list grid-lanes as supported (position verified 27 October 2026).
Photo walls are the usual first project, and a CSS gallery is the natural next build.
