コンポーネントvirtual-masonry
Virtual Masonry
A window-scrolled masonry grid that mounts only the items near the viewport and lays out server-rendered items before first paint, so nothing jumps.
Previewvirtual-masonry
1
2
3
4
5
6
7
8
Installation
pnpm dlx shadcn@latest add https://motionvideo.xyz/r/virtual-masonry.jsonIt installs components/virtual-masonry.tsx and the layout it shares with its first-paint script, lib/masonry-layout.ts. No dependencies beyond React.
Usage
import { VirtualMasonry } from "@/components/virtual-masonry";
import type { MasonryItem } from "@/components/virtual-masonry";
const items: MasonryItem[] = videos.map((video) => ({
key: video.id,
aspectRatio: video.width / video.height,
node: <VideoCard video={video} />,
}));
<VirtualMasonry items={items} />;Items
| Field | Type | |
|---|---|---|
key | string | Stable and unique: it identifies the item across renders and measurements |
aspectRatio | number | Width ÷ height of fixed-ratio media, such as images and video. Omit it to measure the rendered item instead |
lane | number | Pin the item to a lane, counted from 0, instead of the shortest one |
node | ReactNode | What to render; it fills the lane's width |
How it works
- Items fill the shortest lane in order. The number of lanes follows the grid's width: 1 below 560px, then 2, 3, 4 and 5 from 560, 900, 1200 and 1600px, with a 12px gap.
- The grid scrolls with the window and mounts only the items within 900px of the viewport, so thousands of items stay cheap.
- Fixed-ratio items are sized from
aspectRatiowithout measuring. The rest are measured once rendered, and the layout updates as they resize. - In a server render, a small script runs while the page is still parsing. It places the server-rendered items at the real width before they first paint, then removes itself, and hydration adopts its layout. It works in any React server render: Next.js, TanStack Start or Remix.