Grid Rows Masonry

Use grid-template-rows: masonry today.

Grid Rows Masonry is a ponyfill for the CSS masonry layout, to bring the feature to browsers that don’t yet support it. It reflows items using a lightweight algorithm that respects your CSS Grid columns and gaps without absolute positioning and without changing the order of elements in the DOM.

Why this over legacy “masonry” libs?

• Future-forward: mirrors the emerging CSS masonry model; easy to retire when native support lands.
• Tiny & dependency-free: zero deps, fast to initialize.
• Works anywhere: vanilla JS or React.

Quick start

1) Install

npm

npm install grid-rows-masonry

pnpm

pnpm add grid-rows-masonry

yarn

yarn add grid-rows-masonry

2) Usage

Vanilla JS

<div
  id="my-grid"
  style="display: grid; grid-template-columns: repeat(3, 1fr); grid-template-rows: masonry; gap: 20px"
>
  <!-- your variable-height items -->
</div>

<script type="module">
  import { Masonry } from "grid-rows-masonry";

  const el = document.getElementById("my-grid");
  const masonry = new Masonry(el);

  // later, if you need to remove all modifications:
  // masonry.destroy();
</script>

React

import { Masonry } from "grid-rows-masonry/react";

export default function Gallery() {
  return (
    <Masonry
      style={{
        display: "grid",
        gap: 20,
        gridTemplateColumns: "repeat(3, 1fr)",
        gridTemplateRows: "masonry",
      }}
    >
      {/* children with variable heights */}
    </Masonry>
  );
}

Comparison

| Package | Type | Key Features | Differentiators | | --------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Grid Rows Masonry | Ponyfill (vanilla + React) | Simulates grid-template-rows: masonry; zero dependencies; lightweight; works with CSS Grid. | Future-forward CSS Grid approach; minimal overhead; no reliance on virtualization or CSS flexbox. | | masonry-layout | Vanilla JS library (Desandro) | Classic masonry layout; long-established; works with containers, item selectors. (npm, GitHub) | Mature and popular, but heavyweight and reliance on manual initializations. | | react-layout-masonry | React component | Flexible & customizable; no dependencies; modern React-friendly API. (npm) | Built for React, but less focus on CSS Grid polyfill approach. | | masonic | React virtualized component | Virtualized rendering; high performance with large lists; hooks/utils exposed; supports TypeScript. (npm, GitHub) | Best for massive item sets—adds complexity, dependencies, and virtualization. | | react-responsive-masonry | React, CSS Flexbox | Responsive columns and gutter breakpoints; lightweight and CSS-driven. (npm) | Pure flexbox; good for responsiveness but deviates from Grid spec and lacks ponyfill behavior. | | react-masonry | React component | Simple layout stacking by measuring and positioning elements; minimal React dependency. (npm) | Straightforward but lacks modern CSS features or Grid integration. | | CSS Grid masonry polyfill (@prof-dev/masonry) | Vanilla JS polyfill | Detects browser support for grid-template-rows: masonry, falls back to simulation; CSS Grid-based. (GitHub) | Similar concept, but does not reorder items. | | react-plock | React component | Ultra tiny (<1 kB gzipped), balanced layout, responsive, tree-shakeable. (GitHub) | Extremely lightweight and performance-oriented, but focuses on React only. |

Live demos

• Vanilla CodeSandbox
• React CodeSandbox

API

new Masonry(root: HTMLElement)

Initializes the ponyfill on a Grid container (display: grid) with 2+ columns.

Methods

• destroy(): void — restores original DOM order / margins.

Best practices

• Define columns & gaps in CSS; the ponyfill only computes vertical placement.
• No need to reinitialize when content changes–the library responds to mutations of the grid element, and updates the layout.

Used by

Are you using grid-rows-masonry? Open a PR to add your logo/link here!

Dependents list: https://github.com/bartram/grid-rows-masonry/network/dependents

FAQ

Does this change DOM order?
No. It uses grid-column-start to change the column placement of elements to ensure the best fit, but DOM elements are never added or removed.

Will it conflict with native masonry later?
No. When native grid-template-rows: masonry is supported by the user's browser, it will feature-detect and skip initialization.

Contributing

Issues and PRs welcome!

License

ISC © Bartram Nason