Black Friday is here 🔥 Get Wensity Pro for 20% less with

Masonry Grid

Pro

A Pinterest-style React masonry grid on native CSS Grid Lanes, with a JS fallback.

masonrygridgalleryimageslayout
Masonry Grid component preview

Overview

Masonry Grid is a React and Tailwind CSS masonry layout that packs images of different heights into balanced columns, in Next.js or any React app. Browsers with CSS Grid Lanes place tiles natively; elsewhere a fallback drops each tile into the shortest column. Tiles stay in one list in source order, so keyboard focus and screen readers follow your data rather than the columns. minColumnWidth and maxColumns decide how many columns fit, caption puts titles under or over each photo, and only the images fade in. Pass every image's width and height so its tile holds space while loading.

Installation

Run the following command

~/your-project
pnpm dlx wensity@latest add masonry-grid

Usage

Import MasonryGrid from @/components/wensity/masonry-grid and render it anywhere in your React or Next.js app. The source lands in your own repo, so every prop, class and animation below is yours to edit.

app/example.tsx
import { MasonryGrid } from "@/components/wensity/masonry-grid";
export default function Example() {
return (
<MasonryGrid
items={[
{
id: "turntable",
src: "https://assets.wensity.com/photos/objects-still-life/vinyl-turntable-deck.webp",
alt: "Vinyl record on a turntable",
width: 1370,
height: 1148,
title: "Side B",
meta: "Still life",
href: "/pins/turntable",
},
]}
/>
);
}

Props

PropTypeDefaultDescription
itemsMasonryGridItem[]18 photosImage tiles in reading order. Each needs src, alt, width and height; title, meta, href and color are optional.
childrenReactNode-Custom tiles instead of items. Each child becomes one tile, in order.
minColumnWidthnumber160Narrowest a column may get before the grid drops a column, in pixels.
maxColumnsnumber4Most columns the grid will show on wide screens.
columnsnumber-Fixed column count. Overrides minColumnWidth and maxColumns.
gapnumber16 (10 under 480px)Space between tiles, in pixels. Leave it unset for the responsive default.
radiusnumber14Corner radius of each image, in pixels.
caption"below" | "overlay" | "none""below"Titles under the image, over it on hover and focus, or hidden.
engine"auto" | "native" | "js""auto"auto uses CSS Grid Lanes when supported and the JS fallback otherwise.
onItemClick(item, index) => void-Makes image tiles buttons. Tiles with an href are links instead.
emptyStateReactNode"Nothing here yet."Shown when there are no tiles.
  • Split-Flap Display component preview

    Split-Flap Display

    A ceramic and graphite split-flap device that ripples each flap into your message.

  • Interactive 3D Globe component preview

    Interactive 3D Globe

    A 3D Earth lit day and night from the real sun position, wrapped in a soft atmosphere, with smooth drag-to-orbit controls.

  • Animated Code Diff Viewer component preview

    Animated Code Diff Viewer

    Inline or toggled code diffs rendered inside the same polished code block frame, flipping between before and after.

  • Animated Terminal component preview

    Animated Terminal

    A terminal UI with self-typing commands, CRT phosphor glow and scanlines, streaming output that never re-renders a line.