A responsive, highly optimized, unstyled masonry UI layout component. With virtualization, built for being used alongside BaseUI in React 19 projects. Made to be highly portable.

This component is meant to be vendored, not treated as a fixed npm dependency. Copy the file into your repository, read it, and change it to match your team's standards and goals.

npm install @base-ui/react @base-ui/utils

pnpm add @base-ui/react @base-ui/utils

bun add @base-ui/react @base-ui/utils

masonry.tsx

Import the parts, and assemble them together.

import { MasonryRoot, MasonryItem } from "@/components/ui/masonry";

return (
    <MasonryRoot items={items} columnCount={6} gap={12}>
        {(item) => (
            <MasonryItem key={item.id}>
                <Card>...</Card>
            </MasonryItem>
        )}
    </MasonryRoot>
);

Use the render prop to compose a part with your own React components.

For example, MasonryItem renders a <div> by default. The code snippet below shows how to use a custom button instead.

<MasonryItem key={item.id} render={<MyButton size="md" />}>
    ...
</MasonryItem>

The custom component must forward the ref, and spread all the received props on its underlying DOM node. Learn more

Run bun run size:update to refresh.

Groups all parts of the masonry layout. Renders a <div> element.

MasonryRoot Props:

MasonryRoot Data Attributes:

A single item of the masonry layout. Renders a <div> element.

MasonryItem Props:

MasonryItem Data Attributes:

MasonryItem ARIA Attributes:

Masonry renders a list of listitem slots by default. Override role on either part when the content needs different semantics (for example role="feed" / role="article").

MasonryRoot is a client component that server-renders safely.

• Without JavaScript there are no measurements, so the server HTML holds the fallback prop when items is non-empty, or an empty box otherwise. Only the rendered window is in the HTML (windowing).
• Replacing the estimate with measured heights can cause minor layout shift; realistic itemHeight/gap values minimize it.

Affordances that peer virtualizers (react-window, TanStack Virtual, react-virtuoso) ship, which this component deliberately lacks. Listed so you can decide whether they matter before vendoring:

• No imperative API. For jump-to-item UIs: Rendered items expose data-index, so you can find one with container.querySelector('[data-index="42"]') and call scrollIntoView(). Items outside the rendered window have no DOM node — scroll to an estimated offset derived from itemHeight instead, then refine once the item mounts.
• No RTL support. Columns are placed left-to-right, so direction: rtl does not mirror the layout: the first column remains leftmost even when the reading order is right-to-left. Screen-reader order follows source order.
• No column spanning or variable column widths. Every item occupies exactly one equal-width column. There is no colSpan prop. For hero/feature tiles, render a separate block above or below MasonryRoot, or use CSS grid for that section.
• Vertical-only; no horizontal mode. Windowing runs on scrollTop/windowHeight and the container height is the tallest column.
• No per-item height seeding. Only the uniform itemHeight estimate exists; real heights always come from ResizeObserver. When image aspect ratios are known at render time, pick a realistic itemHeight to minimize shift — known per-item heights cannot be passed in to skip measurement.
• No enter/exit animation support. Filtering, insertion, and removal re-layout immediately, and off-window items unmount by design. CSS transition on transform and layout-animation libraries fight measurement. For small animated lists, use overscan={Infinity} to disable windowing first.
• columnWidth is a preferred width used to derive the column count. Items will always try to stretch to fill their (equal-width) columns for consistency.
• Items need a stable identity. Each item must have a string or number id property (or supply getItemKey). The identity keeps measured heights attached to their item across reorders, insertions, and removals; without it, a reorder discards the measured heights and the layout is re-measured. The key you set on MasonryItem in the render function is for React reconciliation only — the id/getItemKey identity is what the layout uses.
• The rendered window extends further below the viewport than above it: scrolling down races the unmeasured frontier (render + measurement lag), while everything above is already placed and only needs render-lag cover.

Open to pull requests & suggestions.

This project is licensed under the MIT License - see the LICENSE file for details.