Masonry Row Grid Layout
A row-first masonry grid that keeps photographs at a readable height and both edges of every row flush, solved with dynamic programming.
- #layouts
- #masonry-grid
- #performance
- #responsive-design
Column-first masonry, the CSS columns kind, reads top to bottom. That is
wrong for a photo grid, because the eye reads left to right and the second
image in the DOM lands halfway down the page. This is the row-first
arrangement instead. The component fills each row to the container's width and
scales it to a height near the target, so neighbouring photographs end up the
same height and both edges of the row stay flush.
Drag the thumb to see what the layout does as the container narrows.
Download
The component, the row solver. Put them adjacent to each other.
Choosing the rows
The greedy arrangement is the obvious one: keep adding images until the row overflows, then scale the row down to fit. It is one pass and it is fast, but it never reconsiders. One tall portrait early on pushes a short row, and the last row is whatever happens to be left.
The justified arrangement treats it as a shortest-path problem. Every break
point costs the squared distance between the row's height and the target, a
row with a single item costs an extra penalty, and dp[i] is the cheapest way
to arrange the first i images. Backtracking through parent[] gives the
rows. It is O(n²) in the worst case, and the inner loop stops as soon as the
row gets shorter than the minimum, so it only examines the items that could
share one row.
The difference is easiest to see side by side. Here are the same twenty photographs in the greedy arrangement.
Measuring, not laying out
MasonryRowGrid never reads a DOM node to decide anything. The items carry
their intrinsic width and height, the only measurement is the container's own
width from a ResizeObserver, and the component computes every position from
those two numbers. That is why a drag holds its frame rate. Resizing re-runs
the arithmetic instead of reading styles back out of the browser.
The observer's callback coalesces into a requestAnimationFrame, so a drag
that fires a hundred resize notifications still produces one layout per frame.
Using it
The component decides position and size. renderItem decides what goes
inside each item container.
Layout modes
naive fills each row until it overflows the container, then scales that row
down to fit. It never revisits a row, so a row is final once it closes, and
appending items cannot move what is already on screen. The cost is the last
row, which holds whatever was left over and is often short.
justified solves all the rows together, so every row is flush and heights
stay near the target. Adding an item re-solves the whole arrangement, so rows
that were already placed can shift.
Structure
The component positions every item absolutely inside one relative container, so the container needs the computed total height. The gap is padding inside each item rather than a margin between items, which keeps the row arithmetic in whole container widths.
Props
<MasonryRowGrid />
items?GridItemProps[]
The items to arrange. Each one carries its intrinsic width and height.
- Default
[]
renderItem?(item, index, measures) => React.ReactNode
Renders the contents of one item container. Return null to leave it empty.
layout?"naive" | "justified"
Which arrangement to solve for. See Layout modes above.
- Default
"naive"
targetHeight?number
The row height to aim for, in pixels.
- Default
300
scaleFactor?number
Tolerance around targetHeight, as a fraction. At 0.1 a row may be a tenth shorter or taller than the target.
- Default
0.1
gap?number
Gutter in pixels, applied as padding inside each item container.
- Default
8
containerProps?React.HTMLAttributes<HTMLDivElement>
Forwarded to the root container. Its className and style merge with the computed ones.
itemProps?React.HTMLAttributes<HTMLDivElement>
Forwarded to every item container, under the same merge.
GridItemProps
widthnumber
Intrinsic width. Only the ratio against height matters, so any consistent unit works.
heightnumber
Intrinsic height.
[key: string]?unknown
Anything else the item carries, such as a source or an id. It reaches renderItem untouched.
Measures
widthnumber
Solved width of the item container, in pixels.
heightnumber
Solved height, shared by every item in the row.
topnumber
Offset from the top of the root container.
leftnumber
Offset from the left of the root container.
indexnumber
Position within the row, from zero. Zero is the row's left edge.
rowNonumber
Row number, from one.
totalItemsInRownumber
How many items share the row, so an item can tell it is the last one.
Files in this entry
Saved beside the document, and served as-is.
Related entries
useIntersectionObserver hook
Track element visibility for lazy loading, infinite scroll and scroll-spy navigation.
Virtual list
Render only the visible slice of a long list, using fixed-height windowing and an absolute spacer.
SVG Particles
Turn an SVG path into a canvas particle field by painting it once, reading the pixels back, and animating the dots under the cursor.



















