Masonry wall of tiles with mixed aspect ratios that keeps source order left to right, with category chips that filter the wall and tiles that glide into their new places.
masonrygallerygridportfolioimagesfilterlayout
When to use it
Use it for
- Portfolios, lookbooks and case-study walls where images have different shapes and shouldn't be cropped to one ratio.
- Mood boards and inspiration pages with a handful of categories to filter.
What it needs from your app
- Each item's aspect ratio (width ÷ height) up front, so tiles reserve their space before the image loads.
Limits
- Grid layout measures every tile in the browser; with JavaScript off it falls back to estimated heights.
- Built for tens of items, not thousands: there is no virtualisation or infinite scroll.
Pairs with
- Feature Grid: A bento grid for a few curated features; the masonry wall for many items of unknown shape.
Installation
$npx shadcn@latest add @geturui/masonry-gallery
Usage
usage.tsx
1import { MasonryGallery } from "@/components/blocks/masonry-gallery";
2
3export default function Work() {
4 return (
5 <MasonryGallery
6 heading="Recent work"
7 items={[
8 { title: "Harbour at dawn", caption: "Lisbon", category: "Travel", ratio: 4 / 5, src: "/work/harbour.jpg", alt: "Fishing boats moored at sunrise" },
9 { title: "Studio portrait", caption: "Editorial", category: "People", ratio: 3 / 4, src: "/work/portrait.jpg", alt: "A woman in a red coat against a grey wall" },
10 { title: "Market stalls", caption: "Marrakesh", category: "Travel", ratio: 16 / 10, src: "/work/market.jpg", alt: "Spice stalls under striped awnings", href: "/work/market" },
11 ]}
12 />
13 );
14}
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | MasonryItem[] | — | { title, ratio, caption?, category?, src?, alt?, art?, href? }. `ratio` is width ÷ height. |
layout | "grid" | "columns" | "grid" | grid: measured row spans, reads left to right in source order. columns: CSS multi-column, no JavaScript layout, reads down each column. |
filter | boolean | true | Category chips above the wall, shown when items have two or more categories. |
eyebrow / heading / subheading | string | — | Section copy. |
className | string | — | Classes for the outer section. |
Accessibility
- In grid layout, keyboard and screen-reader order matches the visual order: left to right, then down.
- Filter chips are buttons with aria-pressed, and a polite live region announces how many items are shown.
- Images need alt text; the drawn placeholders are aria-hidden. Linked tiles have a visible focus ring.
- Tiles fade in without movement under reduced motion, and filtering doesn't animate positions.