# masonry-snap-grid-layout
**Masonry grid layout for React, Vue 3, Angular, and Vanilla JS.**
Pinterest-style responsive image galleries with scroll virtualization and SSR.
One framework-agnostic layout core. Four adapters. Zero dependencies.
[](https://www.npmjs.com/package/masonry-snap-grid-layout)
[](https://www.npmjs.com/package/masonry-snap-grid-layout)
[](https://www.jsdelivr.com/package/npm/masonry-snap-grid-layout)
[](https://bundlephobia.com/package/masonry-snap-grid-layout)
[](https://github.com/khachatryan-dev/masonry-snap-grid-layout/actions)
[](https://github.com/khachatryan-dev/masonry-snap-grid-layout/blob/main/package.json)
[](https://github.com/khachatryan-dev/masonry-snap-grid-layout/blob/main/tsconfig.json)
[](https://socket.dev/npm/package/masonry-snap-grid-layout)
[](https://github.com/khachatryan-dev/masonry-snap-grid-layout/blob/main/LICENSE)
**Try it**
[](https://codesandbox.io/p/sandbox/l9xl7s)
[](https://codesandbox.io/p/sandbox/rgxsxp)
[](https://codesandbox.io/p/devbox/r58pdw)
[](https://github.com/khachatryan-dev/masonry-snap-grid-layout/tree/main/examples)
---
## Overview
`masonry-snap-grid-layout` is a **zero-dependency**, **TypeScript-first** masonry layout
engine for building Pinterest-style grids and responsive image galleries. It ships
first-class components for **React**, **Vue 3**, and **Angular**, plus a plain
**Vanilla JS** class — all driven by the same core, so every adapter produces identical
placement.
It uses **native CSS masonry** where a browser supports it and falls back to a fast JS
engine everywhere else, with no configuration either way. Items are placed by a
shortest-column-first algorithm:
```
┌──────────┐ ┌──────────────┐ ┌─────────┐
│ Card 1 │ │ Card 2 │ │ Card 3 │
└──────────┘ │ (tall) │ └─────────┘
┌───────────┐ │ │ ┌─────────────┐
│ Card 4 │ └──────────────┘ │ Card 5 │
│ (tall) │ ┌──────────┐ │ │
└───────────┘ │ Card 6 │ └─────────────┘
└──────────┘
```
The layout is **self-healing**. Images decoding, web fonts swapping, and embeds resizing
each trigger an automatic relayout, so you never hit the classic masonry failure of items
overlapping because they were measured before their content settled — no
`imagesLoaded`-style helper required.
It also handles the parts most masonry libraries leave to you: **scroll virtualization**
for very large lists (against the page or any scrollable panel), **responsive column
breakpoints**, **server-side rendering** for Next.js and Nuxt, and **keyed
reconciliation** so reordering or filtering a list does not scramble it.
---
## Table of Contents
- [Why this library](#why-this-library)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start) · [Vanilla JS](#vanilla-js) · [React](#react) · [Vue 3](#vue-3) · [Angular](#angular)
- [API Reference](#api-reference)
- [Layout Modes](#layout-modes)
- [Columns and Breakpoints](#columns-and-breakpoints)
- [Images and Async Content](#images-and-async-content)
- [Virtualization](#virtualization)
- [Item Identity](#item-identity)
- [Server-Side Rendering](#server-side-rendering)
- [Recipes](#recipes)
- [Engine Comparison](#engine-comparison)
- [Browser Support](#browser-support)
- [Package Exports](#package-exports)
- [TypeScript](#typescript)
- [Performance](#performance)
- [Running Examples Locally](#running-examples-locally)
- [Testing](#testing)
- [Upgrading](#upgrading)
- [FAQ](#faq)
- [Contributing](#contributing)
- [License](#license)
---
## Why this library
- **One engine, four frameworks.** The layout algorithm is not reimplemented per
adapter, so React, Vue, Angular, and Vanilla produce byte-identical placement.
- **Images actually work.** Per-item observation means a gallery lays out correctly
even though heights are unknown at first paint. Most masonry libraries require you to
wire up an `imagesLoaded`-style helper yourself.
- **Virtualization that fits real apps.** Virtualize against the page _or_ any
`overflow: auto` panel, modal, or dashboard pane — and skip the initial full mount
entirely with `estimatedItemHeight`.
- **SSR-first.** Items are present in the server-rendered HTML, so they are crawlable
and painted before hydration.
- **Small and dependency-free.** Roughly 5 kB gzipped including shared chunks, with a
size budget enforced in CI.
- **Verified across every adapter.** 251 tests covering Vanilla, React, Vue, and
Angular, plus three separate typecheck passes — including a suite that renders in
pure Node with no `window`, testing the real SSR path rather than a jsdom imitation.
---
## Features
| Category | Feature | Detail |
| ------------------ | -------------------------- | ----------------------------------------------------------------------- |
| **Self-healing** | Images & async content | Relayouts when images decode, fonts swap, or embeds resize |
| **Columns** | Explicit & responsive | Fixed `columns`, or a mobile-first map like `{ 0: 1, 640: 2, 1024: 3 }` |
| **Virtualization** | Page or scroll container | Virtualize against the window _or_ any `overflow: auto` element |
| **Large lists** | Estimated heights | `estimatedItemHeight` skips the render-everything measurement pass |
| **CSS-first** | Native CSS masonry | Uses `grid-template-rows: masonry` when the browser supports it |
| **JS engine** | Universal fallback | Absolute-position layout works in every browser today |
| **SSR** | Server-side rendering | Items in the page source — crawlable, painted before hydration |
| **Item identity** | Keyed reconciliation | `getItemKey` reuses DOM nodes across reorders, filters, and prepends |
| **Performance** | Frame-coalesced | Scroll, resize, and image events collapse into one layout per frame |
| **Responsive** | `ResizeObserver` | Recalculates columns automatically on container resize |
| **Animations** | Smooth transitions | GPU-composited CSS `transform` transitions on layout changes |
| **TypeScript** | Fully typed | Generic `` for your data, typed props, slots, and events |
| **Zero deps** | No dependencies | Nothing to audit, nothing to update |
| **Frameworks** | Multi-framework | Vanilla JS · React · Vue 3 · Angular |
---
## Installation
```bash
npm install masonry-snap-grid-layout
```
```bash
yarn add masonry-snap-grid-layout
pnpm add masonry-snap-grid-layout
bun add masonry-snap-grid-layout
```
The stylesheet is required in every framework:
```js
import 'masonry-snap-grid-layout/style.css';
```
Or via CDN:
```html
```
React, Vue, and Angular are **optional peer dependencies** — install only the one you
use. Nothing from the other frameworks is included in your bundle.
---
## Quick Start
### Vanilla JS
```js
import MasonrySnapGridLayout from 'masonry-snap-grid-layout';
import 'masonry-snap-grid-layout/style.css';
const masonry = new MasonrySnapGridLayout(document.getElementById('grid'), {
items,
gutter: 16,
minColWidth: 240,
getItemKey: (item) => item.id, // enables DOM reuse across updates
renderItem: (item, index) => {
const el = document.createElement('div');
el.style.height = `${item.height}px`;
el.textContent = `${index}. ${item.title}`;
return el;
},
});
masonry.updateItems(newItems); // swap the data
masonry.setOptions({ gutter: 24 }); // change options in place
masonry.refresh(); // force a layout pass
masonry.destroy(); // remove styles, stop all observers
```
---
### React
SSR-safe — works with Next.js (App and Pages Router), Remix, and plain Vite.
```tsx
import MasonrySnapGrid from 'masonry-snap-grid-layout/react';
import 'masonry-snap-grid-layout/style.css';
export default function Gallery({ items }) {
return (
item.id}
virtualize
overscan={300}
renderItem={(item) => (
{item.title}
)}
/>
);
}
```
Images need no extra wiring — the grid relayouts as each one decodes.
---
### Vue 3
Drop-in component with a typed scoped slot.
```vue
{{ index }}. {{ item.title }}
```
---
### Angular
A **standalone component** ships with the package, for Angular 17+.
```typescript
import { Component } from '@angular/core';
import { MasonrySnapGridComponent } from 'masonry-snap-grid-layout/angular';
import type { LayoutInfo } from 'masonry-snap-grid-layout';
interface Card {
id: number;
title: string;
height: number;
}
@Component({
selector: 'app-gallery',
standalone: true,
imports: [MasonrySnapGridComponent],
template: `
`,
})
export class GalleryComponent {
items: Card[] = [/* ... */];
trackById = (card: Card): number => card.id;
// renderItem returns a DOM element, so it is defined as a class field
// rather than a method — `this` must stay bound.
renderCard = (card: Card, index: number): HTMLElement => {
const el = document.createElement('div');
el.style.height = `${card.height}px`;
el.textContent = `${index}. ${card.title}`;
return el;
};
onLayout(info: LayoutInfo): void {
console.log(`${info.columnCount} columns`);
}
}
```
Import the stylesheet once in `src/styles.css`:
```css
@import 'masonry-snap-grid-layout/style.css';
```
> **Two Angular caveats.** `renderItem` returns an `HTMLElement`, so Angular templates
> and directives cannot be used for item content — build the element imperatively, or
> drive the engine directly (below) and project your own template. Virtualization is
> **not** available in Angular; use React or Vue if you need it.
Using the engine directly instead of the component
```typescript
import {
Component,
AfterViewInit,
OnDestroy,
ViewChild,
ElementRef,
} from '@angular/core';
import MasonrySnapGridLayout from 'masonry-snap-grid-layout';
@Component({
selector: 'app-root',
standalone: true,
template: ``,
})
export class AppComponent implements AfterViewInit, OnDestroy {
@ViewChild('grid') gridRef!: ElementRef;
private masonry?: MasonrySnapGridLayout;
ngAfterViewInit(): void {
this.masonry = new MasonrySnapGridLayout(this.gridRef.nativeElement, {
items: this.items,
gutter: 16,
renderItem: (item) => {
const el = document.createElement('div');
el.textContent = item.title;
return el;
},
});
}
ngOnDestroy(): void {
this.masonry?.destroy();
}
}
```
---
## API Reference
### Core options
Shared by the Vanilla engine and every adapter. Only `items` and `renderItem` are
required.
| Option | Type | Default | Description |
| --------------------- | ---------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| `items` | `T[]` | **required** | Array of data items to render. |
| `renderItem` | `(item: T, index: number) => HTMLElement` | **required** | Returns the DOM element for each item. React and Vue use JSX/slots instead. |
| `layoutMode` | `'auto' \| 'js'` | `'auto'` | `'auto'` uses native CSS masonry when supported, else JS. `'js'` always uses JS. |
| `gutter` | `number` | `16` | Gap between items, in pixels. |
| `minColWidth` | `number` | `250` | Minimum column width, in pixels. Determines the column count. |
| `columns` | `number \| Record` | — | Fixed column count, or a breakpoint map. Overrides `minColWidth`. [Details](#columns-and-breakpoints) |
| `animate` | `boolean` | `true` | Smooth CSS `transform` transitions on layout changes. |
| `transitionDuration` | `number` | `400` | Transition length in ms (JS mode only). |
| `observeItemResize` | `boolean` | `true` | Relayout when an item's own size changes. [Details](#images-and-async-content) |
| `watchImages` | `boolean` | `true` | Also listen for `load` / `error` on images inside items. |
| `estimatedItemHeight` | `number` | — | Height assumed before measurement. [Details](#very-large-lists) |
| `getItemKey` | `(item: T, index: number) => string \| number` | — | Stable item identity. [Details](#item-identity) |
| `onLayout` | `(info: LayoutInfo) => void` | — | Called after each layout pass. |
### Vanilla JS methods
```ts
masonry.updateItems(items: T[]) // Swap items and re-layout
masonry.setOptions(partialOptions) // Change any option in place, including layoutMode
masonry.refresh() // Force a layout pass
masonry.destroy() // Remove layout styles, stop all observers
```
`refresh()` is rarely needed — item resizes, image loads, and container resizes are all
detected automatically. Reach for it only after mutating item content directly.
### React props
All core options apply, plus:
| Prop | Type | Default | Description |
| ----------------- | ----------------------------------------------- | ------------ | --------------------------------------------------------------------------- |
| `renderItem` | `(item: T, index: number) => ReactNode` | **required** | JSX render function (returns React elements, not `HTMLElement`). |
| `virtualize` | `boolean` | `false` | Only render items in or near the viewport. |
| `overscan` | `number` | `300` | Extra pixels above and below the viewport to keep rendered. |
| `scrollContainer` | `HTMLElement \| RefObject \| Window \| () => …` | `window` | Scrolling viewport to virtualize against. [Details](#in-a-scroll-container) |
| `getItemKey` | `(item: T, index: number) => React.Key` | index | Stable React `key`. |
| `className` | `string` | — | Extra CSS class on the container. |
| `style` | `CSSProperties` | — | Extra inline styles on the container. |
### Vue props, slots, and events
Core options apply as kebab-case props (`:gutter`, `:min-col-width`, `:columns`), plus:
| Prop | Type | Default | Description |
| ------------------ | ---------------------------------- | -------- | ------------------------------------------ |
| `virtualize` | `boolean` | `false` | Only render items in or near the viewport. |
| `overscan` | `number` | `300` | Extra pixels to keep rendered. |
| `scroll-container` | `HTMLElement \| Window \| () => …` | `window` | Scrolling viewport to virtualize against. |
| `get-item-key` | `(item: T, i: number) => key` | index | Stable `:key`. |
| Slot | Slot props | Description |
| ---------- | ---------------------------- | ----------------------- |
| `#default` | `{ item: T, index: number }` | Template for each card. |
| Event | Payload | Description |
| -------- | ------------ | ------------------------------- |
| `layout` | `LayoutInfo` | Emitted after each layout pass. |
Exposed via template ref: `refresh()` forces a layout pass.
### Angular inputs and outputs
Selector: `masonry-snap-grid`. Import `MasonrySnapGridComponent` from
`masonry-snap-grid-layout/angular`.
| Member | Kind | Notes |
| ------------ | --------- | -------------------------------------------------------- |
| Core options | `@Input` | Every option in the core table is available as an input. |
| `layout` | `@Output` | Emits `LayoutInfo` after each layout pass. |
| `refresh()` | method | Force a layout pass. |
Virtualization is not available in Angular.
### Types
```ts
import type {
MasonryOptions,
LayoutMode, // 'auto' | 'js'
LayoutInfo,
ColumnsOption, // number | Record
ItemPosition, // { x, y, width }
} from 'masonry-snap-grid-layout';
interface LayoutInfo {
columnCount: number;
columnWidth: number;
containerHeight: number;
itemCount: number;
engine: 'css' | 'js';
}
```
---
## Layout Modes
| Mode | When to use | Browser support |
| ------------------ | ---------------------------------------------------------------- | --------------- |
| `'auto'` (default) | Always — picks the best available engine automatically | All browsers |
| `'js'` | When you need identical behaviour everywhere, or force JS layout | All browsers |
`'auto'` detects support at runtime via
`CSS.supports('grid-template-rows', 'masonry')`, so it can never apply the property to a
browser that does not implement it.
Native CSS masonry is still **experimental and unshipped by default** — Firefox has it
behind a flag, Chromium has trialled it behind a flag, and the specification itself is
unsettled (`grid-template-rows: masonry` versus the competing `display: masonry`
proposal). In practice almost every visitor gets the JS engine today. Because the check
happens at runtime, `'auto'` will start using the native path if and when a browser
ships it.
> **Important:** `'auto'` changes engine based on the visitor's browser, and the CSS
> engine supports neither virtualization nor transform animations. If you depend on
> either, set `layoutMode="js"` explicitly so behaviour is identical everywhere.
---
## Columns and Breakpoints
By default the column count is derived from `minColWidth` — as many columns of at least
that width as will fit. For exact control, use `columns`.
```tsx
// A fixed number of columns, regardless of container width
// Mobile-first breakpoint map: minimum container width -> column count
```
Breakpoint keys are **minimum container widths**, so they read exactly like a
`min-width` media query: one column until 640px, two from 640px, three from 1024px. The
widest key at or below the current width wins, and keys are compared numerically so
declaration order does not matter.
Two details worth knowing:
- Breakpoints track the **container**, not the viewport — a grid inside a sidebar
responds to the sidebar's width.
- `columns` overrides `minColWidth`. An unusable value (`0`, negative, `NaN`, an empty
map) falls back to the `minColWidth` calculation rather than producing a broken grid.
---
## Images and Async Content
Masonry has to measure item heights to place them, but images, web fonts, and embeds all
settle **after** that first measurement. A grid measured against undecoded images is laid
out with the wrong heights.
**This is handled for you.** Every item is watched with its own `ResizeObserver`, and
images inside items get `load` / `error` listeners, so the grid relayouts as content
settles:
```tsx
// Nothing to configure — images just work.
}
/>
```
Every trigger — 200 images finishing at once, a font swap, a container resize — is
coalesced into **one** layout pass per animation frame, so a burst costs a single
relayout rather than one per event.
Opt out if your items are fixed-height and you want to skip the observers entirely:
```tsx
```
> **Tip:** setting `width` / `height` or `aspect-ratio` on your images still helps. It
> gives the browser a correct box before the image decodes, avoiding the visible reflow
> that self-healing would otherwise have to correct.
---
## Virtualization
For large lists, enable virtualization so only the visible portion of the grid is in the
DOM.
```tsx
// React
```
```vue
```
**How it works:**
1. Heights are measured and cached.
2. Only items within `viewport height + overscan` stay in the DOM.
3. The container height is computed from **all** items, so the scrollbar stays correct.
4. Cached heights position off-screen items, so nothing shifts as you scroll.
Scroll and resize events are coalesced into at most one update per animation frame, and
the container's offset is re-read each frame — so a sticky header collapsing mid-scroll
cannot desynchronise the visible window.
### In a scroll container
By default virtualization tracks the page. To virtualize inside an `overflow: auto`
panel, modal, or dashboard pane, point it at the element:
```tsx
function Panel({ items }) {
const scrollRef = useRef(null);
return (
);
}
```
```vue
```
`scrollContainer` accepts an element, a React ref, a getter function, `window`, or
`'window'`. Memoize getter functions — a new identity resubscribes the listeners.
### Very large lists
By default virtualization must mount every item once to learn its height, which defeats
the purpose for tens of thousands of items. Supply `estimatedItemHeight` and positions
are estimated up front, so the very first render is already clipped:
```tsx
```
Real measurements replace the estimate as items scroll through. A rough estimate is
fine — an inaccurate one only means the scrollbar length adjusts as you scroll.
> Virtualization is JS-mode only. CSS masonry mode always renders every item, since the
> browser handles placement natively.
---
## Item Identity
By default items are keyed by array index. That is fine for append-only lists, but if
your list can be **reordered, filtered, sorted, or prepended to**, index keys mean the
DOM node at position `i` gets reused for whatever item now sits there — carrying its
cached height with it.
Pass `getItemKey` to give items real identity:
```tsx
item.id} renderItem={...} />
```
What it changes per adapter:
- **React / Vue** — becomes the `key`, so nodes move instead of being rebuilt.
- **Vanilla / Angular** — enables keyed reconciliation, so `updateItems()` reuses
existing elements instead of clearing the container. That preserves focus, text
selection, scroll position inside items, and in-flight media playback.
---
## Server-Side Rendering
Items are rendered into the initial HTML inside a responsive CSS grid, so they are in the
page source for crawlers and painted before hydration.
1. The server renders every item inside a plain responsive CSS grid.
2. The browser paints that immediately — fast First Contentful Paint.
3. The client hydrates, measures item heights, and applies masonry transforms.
4. `ResizeObserver` keeps the layout correct from then on.
Because step 3 moves items from grid positions to masonry positions, expect one
transition after hydration. Setting `animate={false}` makes it instant rather than
animated.
### Next.js
Add `'use client'` in the App Router, since the component uses browser APIs after
hydration:
```tsx
'use client';
import MasonrySnapGrid from 'masonry-snap-grid-layout/react';
import 'masonry-snap-grid-layout/style.css';
```
No directive is needed in the Pages Router.
### Nuxt
The Vue component works with SSR out of the box. Import the stylesheet in
`nuxt.config.ts`:
```ts
export default defineNuxtConfig({
css: ['masonry-snap-grid-layout/style.css'],
});
```
---
## Recipes
Responsive image gallery
```tsx
photo.id}
renderItem={(photo) => (
)}
/>
```
Passing `width` / `height` lets the browser reserve the correct box before decode, so
there is nothing for self-healing to correct.
Infinite scroll
```tsx
const [items, setItems] = useState(initial);
item.id} // required: appended items must keep identity
virtualize
estimatedItemHeight={280}
onLayout={({ containerHeight }) => {
if (window.scrollY + window.innerHeight > containerHeight - 600) {
loadMore().then((next) => setItems((prev) => [...prev, ...next]));
}
}}
renderItem={(item) => }
/>;
```
Reading the resolved layout
```tsx
{
console.log(`${info.columnCount} columns of ${info.columnWidth}px`);
console.log(`total height ${info.containerHeight}px via ${info.engine}`);
}}
renderItem={...}
/>
```
---
## Engine Comparison
| | CSS Masonry | JS Masonry |
| ------------------ | ----------------------------- | --------------------------------- |
| **Availability** | Experimental, behind flags | All browsers |
| **Animations** | Limited | Smooth `transform` transitions |
| **SSR** | Yes | Yes |
| **Performance** | Native, GPU | Transform-based, no DOM thrashing |
| **Virtualization** | No | Yes — page or scroll container |
| **Self-healing** | Native | Yes — per-item observers |
| **Column control** | `columns`, or browser decides | Exact `columns` / `minColWidth` |
---
## Browser Support
The JS engine works in every browser that can run the package's ES2020 output.
Two modern APIs are used, both optional:
| API | Used for | Without it |
| ---------------- | ------------------------------------------ | ---------------------------------------------------- |
| `ResizeObserver` | Responsive columns and self-healing layout | Layout still runs; it just does not re-run on resize |
| `CSS.supports` | Detecting native CSS masonry | Falls back to the JS engine |
Both are feature-detected, so there is nothing to polyfill and no crash on older
engines — you simply get a static layout. Server-side rendering touches neither.
---
## Package Exports
| Entry | Contents | min+gzip | min+brotli |
| ------------------------------------ | ---------------------------------------- | ---------------------- | ---------- |
| `masonry-snap-grid-layout` | Vanilla JS class + TypeScript types | **2.8 kB** | 2.5 kB |
| `masonry-snap-grid-layout/react` | React component | **3.6 kB** | 3.2 kB |
| `masonry-snap-grid-layout/vue` | Vue 3 component | **3.8 kB** | 3.4 kB |
| `masonry-snap-grid-layout/angular` | Angular standalone component (TS source) | compiled by your build | — |
| `masonry-snap-grid-layout/style.css` | Required stylesheet | **0.3 kB** | 0.2 kB |
Each figure includes every shared chunk that entry pulls in, and is enforced in CI by
`npm run size`.
`dist/` is published **unminified** — readable inside `node_modules`, and every bundler
minifies it anyway — so the numbers above are measured after minification, matching what
you actually ship and what bundlephobia reports. Loading straight from a CDN with no
build step serves the unminified file instead: ~17 kB raw, ~5 kB gzipped over the wire
for the React entry.
All exports are ESM and tree-shakeable. Importing `/react` includes no Vue or Angular
code, and the Vanilla entry contains no virtualization or scroll-tracking code at all.
---
## TypeScript
Every entry point is fully typed, and the item type flows through generically:
```tsx
interface Photo {
id: string;
src: string;
alt: string;
}
// `item` is inferred as Photo in renderItem and getItemKey
items={photos}
getItemKey={(item) => item.id}
renderItem={(item) => }
/>;
```
The Vue component uses a generic `
