Color scheme

CSS Masonry Layout

A masonry layout is the "Pinterest layout": a grid where columns are strict but rows pack tightly, each item rising to fill the gap left by a shorter item above it rather than snapping to a shared row baseline. The result is a dense, organic arrangement that handles variable-height content without the ugly empty space you get from a standard grid. Developers have wanted this in CSS for over a decade. Getting it there has been one of the most contentious specification debates in recent CSS history.

Before Native CSS: The Workarounds

Because CSS could not pack items this way, developers invented their own solutions. Three approaches dominated.

The CSS Columns Trick

The most common CSS-only workaround uses column-count or column-width to create a multi-column layout. Items flow down each column, packing tightly within it. The result looks like masonry at first glance.


        .gallery {
            column-count: 3;
            column-gap: 1rem;
        }

        .gallery-item {
            break-inside: avoid;
            margin-bottom: 1rem;
        }
    

The problem is reading order. Items flow top-to-bottom down each column, so the DOM order is column 1 top to bottom, then column 2 top to bottom, then column 3. Visually this looks like a grid, but a screen reader or keyboard user tabs through items in the wrong order: all the way down the left column before starting the middle one. For decorative image galleries where order does not matter, this is acceptable. For any content where sequence is meaningful, it is an accessibility failure.

Masonry.js

Masonry.js, created by David DeSandro, became the definitive JavaScript solution. It measures each item's height after render, calculates the shortest column, places the next item there, and repeats. The items live in normal DOM order, which preserves reading order and accessibility. The layout is recalculated on resize.


        var grid = document.querySelector('.grid');
        var masonry = new Masonry(grid, {
            itemSelector: '.grid-item',
            columnWidth: 200,
            gutter: 16
        });
    

Masonry.js weighs around 24KB and requires JavaScript to be available and loaded before the layout is correct. On slow connections or with JavaScript disabled, the layout falls back to a standard stacked flow. It also requires manual recalculation when content changes, such as when images finish loading or new items are added dynamically. Many developers still reach for Masonry.js or its modern lightweight successors precisely because it works today, in every browser, with zero CSS spec uncertainty. The native approach is coming, but Masonry.js is real and proven right now.

JavaScript with Absolute Positioning

Some frameworks, including early Pinterest itself, calculated item positions entirely in JavaScript and used position: absolute on every item. This gives pixel-perfect control but makes the layout invisible to browsers before JavaScript runs, requires complex scroll performance management, and breaks natural document flow entirely.

The Specification Wars

Firefox was the first browser to prototype native CSS masonry layout in 2020, using a grid-template-rows: masonry syntax that integrated packing behavior into CSS Grid. The idea was appealing: Grid already had the column track model, so masonry would just be a different behavior on the row axis.

Then the debate started. Apple's WebKit team and Google's Chrome team agreed that masonry should exist in CSS but disagreed fundamentally about how. WebKit argued it should live inside CSS Grid, giving it access to subgrid, explicit placement, and all of Grid's track-sizing power. Google argued it should be a completely separate display type, citing performance concerns about combining Grid's two-axis track resolution algorithm with masonry's packing algorithm, and pointing out that many Grid features simply do not make sense in a masonry context.

The naming debate ran parallel to the syntax debate and was equally contentious. Over the years, the CSS Working Group considered names including masonry, display: masonry, grid-masonry, waterfall, staggered-grid, and others. The word "masonry" itself drew criticism for being too analogous to the real world compared to other CSS keywords, which tend to be more abstract. Defenders argued that "masonry" had already become common industry vocabulary for this pattern, making the name more intuitive despite its concrete origin.

The CSS Working Group resolved both debates in late 2025. The syntax would reuse Grid templating and placement properties rather than introducing a new display type. The name would be grid-lanes. The keyword masonry was dropped specifically to avoid conflicting with the thousands of existing projects using Masonry.js class names and configuration objects that reference the word. grid-lanes describes the behavior accurately: strict lanes on one axis, free packing on the other.

Kevin Powell covered the naming decision in detail in his November 2025 video display: masonry is officially DEAD. It is worth watching alongside the older Masonry Layout with CSS Only video to see how the thinking evolved.

The grid-lanes Syntax

The settled syntax uses display: grid-lanes with grid-template-columns defining the lane tracks. Items flow into whichever lane has the most available space, packing tightly without leaving gaps. The column axis is strict; the row axis is free.


        .gallery {
            display: grid-lanes;
            grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
            gap: 1rem;
        }
    

Items can still span multiple lanes using grid-column, and explicit placement properties from CSS Grid carry over. The key difference from standard Grid is that there are no row tracks: the browser calculates row positions dynamically based on content height and available space in each lane.

Because grid-lanes is not yet in production browsers, you must use @supports with a meaningful fallback. A regular grid with align-items: start is the closest approximation: items snap to row tracks and gaps appear, but the layout is readable and nothing breaks.


        /* Fallback: standard grid, items snap to rows */
        .gallery {
            display: grid;
            grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
            gap: 1rem;
            align-items: start;
        }

        /* Progressive enhancement: masonry packing where supported */
        @supports (display: grid-lanes) {
            .gallery {
                display: grid-lanes;
            }
        }
    

Browser Status

As of mid-2026, display: grid-lanes is available in Safari Technology Preview and behind a flag in Chrome 140+. It is not yet available in stable production browsers. Firefox prototyped an earlier syntax and is expected to implement grid-lanes, but has not announced a timeline. This feature is worth learning and talking about, but not worth shipping to users without a robust fallback today.

For your Teaching Video, use Masonry.js to demonstrate what the finished layout looks like in practice. Your teammates will understand the concept better from a working demo than from a feature-flag screenshot.

Accessibility: Tab Order and Visual Order

Native grid-lanes solves the reading order problem that CSS columns created. Because items remain in DOM order and the browser places them visually, keyboard navigation and screen reader order match the content's logical sequence. This is a meaningful accessibility improvement over the column trick.

However, grid-lanes does introduce a subtler accessibility concern: the packing algorithm places items based on available space, not on content relationships. A layout where related items should appear near each other may separate them visually after packing. Always consider whether the DOM order and the visual grouping make sense together, and whether users navigating by keyboard will encounter items in an order that follows the content's meaning.

Teaching Video Checklist

When you record your teaching video, make sure your teammates come away understanding these concepts:

  • What masonry layout is and why standard CSS Grid leaves gaps with variable-height content, shown by building a simple grid and showing the problem visually
  • The CSS columns workaround: how it works, why it looks like masonry, and why the tab order problem makes it unsuitable for content where reading sequence matters
  • A working Masonry.js demo on your portfolio that shows the finished packing behavior so teammates understand what grid-lanes will eventually do natively
  • The specification history: why the debate between Apple and Google lasted years, what the naming controversy was about, and why the final answer is grid-lanes rather than masonry
  • The current grid-lanes syntax, its browser status, and the @supports fallback pattern
  • Why some developers still prefer Masonry.js over the native approach and what tradeoffs each carries

Start with the gap problem on a standard grid so teammates feel the pain before you show the solution. Use Masonry.js for the live demo since it works in every browser today. Walk through the spec history briefly but spend more time on the syntax and the fallback strategy.

Resources