CSS Now Natively Supports Masonry Layout – How It Works and How to Use It

Background

Traditional waterfall (masonry) layouts on platforms such as Xiaohongshu and Taobao were built with JavaScript libraries (e.g., Masonry.js, Isotope) or with complex Grid/Flexbox work‑arounds. Those approaches increase bundle size, require manual resize handling, and are prone to bugs.

Standardisation Timeline

2017‑2020 – Community proposals

Developers opened proposals and issues on the W3C GitHub repository requesting native CSS support for masonry because Grid could not express irregular “brick‑wall” arrangements.

2020‑2024 – Specification debate

The CSS Working Group discussed masonry in Grid Level 3. Apple/WebKit advocated a Grid‑variant syntax grid-template-columns: masonry, while Google/Chromium argued for a distinct layout type display: masonry. The debate concluded with a compromise that both syntaxes are allowed.

2025 – Experimental implementation

Chrome and Edge 140 introduced experimental support. The feature must be enabled via chrome://flags → “CSS Masonry Layout”. Firefox Nightly also offers experimental support behind the flag layout.css.masonry.enabled. Safari/WebKit is still in development, with stable support expected in 2026.

Advantages of Native CSS Masonry

Higher performance : the browser engine computes layout directly, avoiding JavaScript DOM manipulation.

Automatic responsiveness : column/row reflow occurs automatically on viewport changes.

Reduced code footprint : no external libraries, no resize listeners, no custom layout scripts.

Faster load : CSS renders immediately; Chrome’s internal tests show roughly a 40 % speed improvement for a 100‑item masonry compared with JavaScript solutions.

Syntax Options

Option 1 – Layout type

.masonry {
  display: masonry;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: 16px;
}

This Chrome‑first syntax treats masonry as a new layout type. The grid-template-columns rule works because masonry inherits part of Grid’s syntax.

Option 2 – Grid extension

.masonry {
  display: grid;
  grid-template-columns: masonry;
}

This syntax integrates masonry into Grid. It is still under discussion and not yet implemented in browsers.

Basic Usage

.masonry {
  display: masonry;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: 16px;
}

The container creates responsive columns with a minimum width of 200 px; the browser determines the column count automatically.

Row‑direction masonry

.masonry {
  display: masonry;
  masonry-direction: row;
  grid-template-rows: repeat(auto-fit, minmax(100px, 1fr));
  gap: 16px;
}

Setting masonry-direction: row switches the flow to rows, useful for horizontal scrolling feeds or timelines.

Automatic column generation

.masonry {
  display: masonry;
  gap: 16px;
  /* columns are generated automatically */
}

If grid-template-columns is omitted, the browser creates columns automatically.

Cross‑column spanning

.masonry {
  display: masonry;
  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
  gap: 16px;
}
.featured-item {
  grid-column: span 2; /* spans two columns */
}
.full-width {
  grid-column: 1 / -1; /* full‑width */
}

Elements can span multiple columns or the full width, similar to CSS Grid.

Shorthand property

.masonry {
  display: masonry;
  masonry: repeat(3, 200px) column;
}

The shorthand combines column count and direction; it is equivalent to setting masonry-direction: column and an explicit grid-template-columns list.

Browser Support

Chrome / Edge 140+ – experimental; enable via chrome://flags.

Firefox Nightly – experimental; enable via layout.css.masonry.enabled.

Safari / WebKit – in development, expected stable support in 2026.

Feature is experimental and not yet ready for production, but it is stable enough for exploration.