MasonryBalanced

MasonryBalanced measures item heights and places each item into the shortest column. Use it when uneven card heights make a regular grid feel lopsided.

Performance7 min read

Designing feeds that still feel fast at 10,000 items

A practical guide to windowing, measurement, and when placeholders improve the scroll experience.

Images4 min read

Treat image dimensions as layout data

Known width and height values let the layout settle before media finishes loading.

Accessibility5 min read

Masonry grids can still be semantic

Source order, list roles, and item metadata matter more than the visual column a card lands in.

Responsive6 min read

Container breakpoints beat viewport assumptions

Use breakpoint maps when the component lives inside panels, sidebars, or resizable workspaces.

Design8 min read

Composing card systems around unknown height

Small differences in copy, badges, and media ratios add up. Balanced placement keeps the page calm.

When to use

Editorial cards with mixed copy length.
Cards with optional badges, metadata, or media.
Image grids where dimensions are known and visual balance matters.

Basic usage

import { MasonryBalanced } from 'masonix';

export function ArticleGrid({ articles }: { articles: Article[] }) {
  return (
    <MasonryBalanced
      items={articles}
      columns={{ 0: 1, 640: 2 }}
      gap={16}
      estimatedItemHeight={220}
      itemKey={(article) => article.id}
      render={({ data }) => <ArticleCard article={data} />}
    />
  );
}

Known heights

When item dimensions are already known, pass getItemHeight to skip the measurement wait.

Marfa, TX

Desert dawn

Seattle, WA

Glass house

Reykjavik, IS

Blue hour

Lisbon, PT

Courtyard

Brooklyn, NY

Studio wall

Kyoto, JP

Quiet arch

Busan, KR

Sea path

Portland, OR

Green room

<MasonryBalanced
  items={photos}
  columns={{ 0: 1, 560: 2, 860: 3 }}
  gap={14}
  defaultWidth={960}
  itemKey={(photo) => photo.id}
  getItemHeight={(photo, _index, columnWidth) =>
    Math.round(columnWidth * (photo.height / photo.width))
  }
  render={({ data, width }) => <PhotoCard photo={data} width={width} />}
/>

Common mistakes

Do not pass unstable keys; measured heights should follow item identity.
Do not use CSS string gaps; balanced placement needs numeric gap values.
Do not set estimatedItemHeight far from real card heights.