Masonry Grid

A fast, lightweight, and responsive masonry grid layout library in vanilla JavaScript.

• 🪶 Lightweight. ~1.4 kB (minified and brotlied). Zero dependencies.
• ⚡ Fast. Direct DOM manipulation with optimized reflow algorithms.
• 📱 Responsive. Automatically adapts to container size changes using ResizeObserver.
• 📘 TypeScript-first.

Read the docs and explore examples at masonry-grid.js.org

<style>
.masonry {
  /* Required styles */
  display: grid;
  overflow: hidden;
  /* Optional styles */
  gap: 10px;
  grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
}

.frame {
  /* Required styles */
  aspect-ratio: var(--width) / var(--height);

  & img {
    width: 100%;
  }
}
</style>
<div class="masonry">
  <!-- Each item must have aspect-ratio set by --width and --height CSS variables -->
  <div class="frame" style="--width: 4; --height: 3;">
    <img src="https://picsum.photos/400/300" />
  </div>
  <div class="frame" style="--width: 1; --height: 1;">
    <img src="https://picsum.photos/200/200" />
  </div>
  <div class="frame" style="--width: 3; --height: 4;">
    <img src="https://picsum.photos/300/400" />
  </div>
  <div class="frame" style="--width: 3; --height: 4;">
    <img src="https://picsum.photos/300/400" />
  </div>
  <div class="frame" style="--width: 1; --height: 1;">
    <img src="https://picsum.photos/200/200" />
  </div>
  <div class="frame" style="--width: 4; --height: 3;">
    <img src="https://picsum.photos/400/300" />
  </div>
</div>
<script type="module">
import { BalancedMasonryGrid as MasonryGrid } from 'https://cdn.skypack.dev/@masonry-grid/vanilla'

new MasonryGrid(document.querySelector('.masonry'))
</script>

Install

pnpm add @masonry-grid/vanilla
# or
npm i @masonry-grid/vanilla
# or
yarn add @masonry-grid/vanilla

Docs

• Guides
• API Reference
• Examples