# Masonry Gallery
> 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.
- Collection: Blocks
- Tier: free
- Docs: https://geturui.com/docs/masonry-gallery
- Install: `npx shadcn@latest add @geturui/masonry-gallery`
- Dependencies: motion, lucide-react
## When to use it
- 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](https://geturui.com/docs/feature-grid): A bento grid for a few curated features; the masonry wall for many items of unknown shape.
## Usage
```tsx
import { MasonryGallery } from "@/components/blocks/masonry-gallery";
export default function Work() {
return (
);
}
```
## 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.
## Source
### components/blocks/masonry-gallery.tsx
```tsx
"use client";
import * as React from "react";
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import { cn } from "@/lib/utils";
export interface MasonryItem {
title: string;
/** Small line under the title, e.g. a credit or a date. */
caption?: string;
/** Used by the filter chips. Items without one only show under "All". */
category?: string;
/** Width ÷ height of the tile, e.g. 4 / 5 for a portrait photo. */
ratio: number;
/** Image URL. Without it the tile shows `art` or a drawn placeholder. */
src?: string;
/** Required with `src`; leave empty only for purely decorative images. */
alt?: string;
/** Your own illustration; used when there is no `src`. */
art?: React.ReactNode;
/** Makes the whole tile a link. */
href?: string;
}
export interface MasonryGalleryProps {
eyebrow?: string;
heading?: string;
subheading?: string;
items?: MasonryItem[];
/**
* "grid": CSS grid with measured row spans, so tiles read left to right in source order (needs JavaScript to size).
* "columns": CSS multi-column, no JavaScript layout, but tiles read down the first column before the second.
*/
layout?: "grid" | "columns";
/** Show category chips above the gallery when items have categories. */
filter?: boolean;
className?: string;
}
const DEFAULT_ITEMS: MasonryItem[] = [
{ title: "Launch keynote slides", caption: "Product · 12 frames", category: "Product", ratio: 4 / 5 },
{ title: "Dashboard empty states", caption: "App UI · 6 frames", category: "App UI", ratio: 4 / 3 },
{ title: "Pricing page study", caption: "Marketing · 9 frames", category: "Marketing", ratio: 3 / 4 },
{ title: "Onboarding checklist", caption: "App UI · 4 frames", category: "App UI", ratio: 1 },
{ title: "Brand colour tokens", caption: "Brand · 3 frames", category: "Brand", ratio: 16 / 10 },
{ title: "Mobile settings", caption: "App UI · 8 frames", category: "App UI", ratio: 9 / 16 },
{ title: "Changelog cards", caption: "Marketing · 5 frames", category: "Marketing", ratio: 5 / 4 },
{ title: "Icon set, 24px", caption: "Brand · 48 icons", category: "Brand", ratio: 1 },
{ title: "Checkout flow", caption: "Product · 7 frames", category: "Product", ratio: 3 / 4 },
{ title: "Status page", caption: "Product · 2 frames", category: "Product", ratio: 4 / 3 },
];
/** Grid mode: rows are ROW px tall with no row gap; each tile spans enough rows for its measured height plus GAP. */
const ROW = 4;
const GAP = 16;
const TONES = ["bg-volt-soft text-volt-ink", "bg-ember-soft text-ember-ink", "bg-surface-raised text-ink-subtle", "bg-surface-sunken text-ink-muted"];
/** Drawn placeholder art from theme tokens, so the gallery works with no image assets. */
function Placeholder({ index }: { index: number }) {
const kind = index % 4;
return (
);
}
function Tile({ item, index, reduce }: { item: MasonryItem; index: number; reduce: boolean }) {
const media = item.src ? (
// Plain so the block has no framework dependency; swap in next/image in a Next.js app.
// eslint-disable-next-line @next/next/no-img-element
) : (
item.art ??
);
const body = (
<>
{media}
{item.title}
{item.caption && {item.caption}}
);
return (
{item.href ? (
{body}
) : (
body
)}
);
}
/** Rows the cell's content needs: measured once mounted (and on resize), estimated from the ratio before that. */
function useRowSpan(ref: React.RefObject, ratio: number) {
const [span, setSpan] = React.useState(() => Math.ceil((300 / ratio + 64 + GAP) / ROW));
React.useEffect(() => {
const el = ref.current;
if (!el) return;
const ro = new ResizeObserver(([e]) => setSpan(Math.ceil((e.contentRect.height + GAP) / ROW)));
ro.observe(el);
return () => ro.disconnect();
}, [ref]);
return span;
}
/** `ref` comes from AnimatePresence's popLayout mode, which lifts an exiting tile out of the grid so the rest move at once. */
function GridCell({ item, index, reduce, ref }: { item: MasonryItem; index: number; reduce: boolean; ref?: React.Ref }) {
const inner = React.useRef(null);
const span = useRowSpan(inner, item.ratio);
return (
);
}
/**
* Masonry gallery of tiles with mixed aspect ratios. Grid mode keeps source order left to right; columns mode is pure CSS.
* Optional category chips filter the tiles, which glide into their new places.
*/
export function MasonryGallery({
eyebrow = "Gallery",
heading = "Recent work, every shape and size",
subheading = "Portrait, landscape and square shots on one wall, with no cropping to a single ratio.",
items = DEFAULT_ITEMS,
layout = "grid",
filter = true,
className,
}: MasonryGalleryProps) {
const reduce = useReducedMotion() ?? false;
const categories = React.useMemo(() => [...new Set(items.map((i) => i.category).filter((c): c is string => !!c))], [items]);
const [active, setActive] = React.useState(null);
const shown = items.map((item, index) => ({ item, index })).filter(({ item }) => !active || item.category === active);
return (
{eyebrow && {eyebrow}}
{heading}
{subheading &&
{subheading}
}
{filter && categories.length > 1 && (
{[null, ...categories].map((c) => {
const on = active === c;
return (
);
})}