Masonry — Cascading Grid Layout Library for the Web

Introduction

Masonry is a JavaScript grid layout library that arranges elements vertically into columns, placing each element in the position where it fits best. The result is a gap-free cascading layout popularized by Pinterest, where items of varying heights pack together efficiently.

What Masonry Does

• Arranges elements into a cascading grid where items fill vertical gaps left by shorter neighbors
• Calculates optimal column placement automatically based on container width and item sizes
• Supports dynamic content by re-laying out when items are added, removed, or resized
• Works with both fixed-width and percentage-based responsive column widths
• Provides layout events and methods for animation integration and lazy loading

Architecture Overview

Masonry measures the height of each child element and maintains an array tracking the current bottom position of each column. For each new item, it identifies the shortest column and positions the item there using absolute positioning. The library depends on Outlayer for its base layout class and get-size for element measurement. Layout recalculation can be triggered manually or automatically when the window resizes.

Self-Hosting & Configuration

• Install via npm, Yarn, or include the script from a CDN
• Initialize on a container element with itemSelector set to the class of child items
• Set columnWidth to a fixed pixel value, a CSS selector for a sizing element, or leave it unset to use the first item's width
• Enable percentPosition: true for responsive layouts that use percentage-based widths
• Call msnry.layout() after dynamically adding or removing items to recalculate positions

Key Features

• Efficient gap-free layout algorithm that packs variable-height items into tight columns
• Responsive by default when combined with percentage widths or CSS media queries
• Stamp feature excludes fixed elements (like featured items) from the layout flow
• Compatible with imagesLoaded plugin to trigger layout after images finish loading
• Works with CSS transitions for animated repositioning when the layout changes

Comparison with Similar Tools

• CSS Columns — native browser feature that flows content into columns but breaks individual items across columns; Masonry keeps items intact
• CSS Grid (masonry value) — an experimental CSS Grid feature (grid-template-rows: masonry) that aims to replicate this layout natively; not yet supported in all browsers
• Isotope — extends Masonry with filtering and sorting capabilities; use Isotope when you need those features, Masonry when you need the layout alone
• Packery — similar bin-packing layout by the same author with draggable support; Masonry is simpler and more performant for static layouts
• Colcade — lightweight column-based layout alternative by the Masonry author; less feature-rich but smaller in bundle size

FAQ

Q: Do I need Masonry now that CSS Grid has a masonry property? A: The CSS grid-template-rows: masonry spec is still experimental and not supported in Chrome or Safari stable as of 2025. Masonry.js remains the reliable cross-browser solution.

Q: How do I handle images that load after layout? A: Use the imagesLoaded library alongside Masonry. Initialize the layout inside the imagesLoaded callback so that element heights are measured after images have rendered.

Q: Can Masonry handle thousands of items? A: Masonry works well for hundreds of items. For very large datasets, consider virtual scrolling or pagination to limit the number of DOM elements, then run Masonry on the visible subset.

Q: Does Masonry work with React or Vue? A: Yes. Initialize Masonry in a useEffect hook (React) or onMounted lifecycle (Vue), passing the container ref. Community wrappers like react-masonry-css provide declarative APIs.

Sources

• https://github.com/desandro/masonry
• https://masonry.desandro.com/