Deterministic geometry, clearly composed.

Install

npm install grid-masonry-core
npm install grid-masonry-react react
npm install grid-masonry-browser

These commands target the coordinated 0.3.0 release. The package release is MIT licensed.

Core concepts

Core accepts immutable items with an aspectRatio and returns container-relative cells. Vertical layouts use columns across x and y flow; horizontal layouts use rows across y and x flow.

const layout = calculateMasonryLayout(items, {
  containerWidth: 960,
  minColumnWidth: 220,
  gap: 8,
});

Input order is canonical. layout.cells, IDs, and cell.index remain source order.

Placement

Use contiguous columnSpan or rowSpan. Preferred lanes are soft intent; locked lanes are hard logical lane constraints and normalize responsively. flowDistribution supports start, end, center, space-between, and space-evenly.

Measured whole-item footprints are { height, forWidth } vertically and { width, forHeight } horizontally. ReservedRegion uses logical { laneStart, laneSpan, flowStart, flowSize } and is hard occupied space without synthetic cells.

Measurement lifecycle

Core resolves the cross size, the host renders natural content, the host measures the natural content surface, and then Core receives a cross-size-bound resolvedFootprint. Do not measure the absolute-positioning shell. Stale bindings fall back to ratio-derived geometry.

State, snapshots, and stable reflow

createMasonryState supports append, update, remove, reorder, resize, inspect, snapshot, and restore. Snapshots are validated checkpoints for the same semantic state, not undo or history; stale/tampered restore fails atomically.

reflowStrategy: "stable" compares bounded compact and retained-lane candidates by total displacement, maximum displacement, moved count, then compact on ties. It is not a global optimizer. calculateFlowAnchorDelta reports geometry only and never changes scroll.

Directions

flowDirection mirrors only the flow axis. crossDirection mirrors only the cross axis. Neither reverses source/DOM order nor implements text RTL. Hosts may use cross reverse for a vertical RTL-style presentation while keeping DOM and accessibility policy separate.

Reserved regions

Regions are logical hard obstacles. Overlapping regions and input permutation do not change geometry. Items sharing lanes respect the flow gap, and region extent contributes to the layout extent. Dense/backfill is not implemented.

Diagnostics, queries, and tolerance

calculateMasonryLayoutWithDiagnostics is opt-in and returns the exact ordinary layout plus structured facts about spans, lanes, footprints, obstacle shifts, and distribution. Linear and indexed flow queries are equivalent; virtualization primitives add overscan without owning scroll.

flowTolerance widens only the lane candidate selection band: eligible candidates satisfy candidate ≤ minimum + tolerance. The chosen lane keeps its exact coordinate; gaps and collision rules do not change.

React and Browser adapters

React exports MasonryGrid, HorizontalMasonryGrid, layout hooks, useOrderList, and virtualization hooks. Browser exports vertical/horizontal controllers and virtualized lifecycle. Both consume Core geometry, preserve identity, and keep DOM/scroll policy in the host.

See the React guide and Browser guide.

Limitations and status

• Dense/backfill and React Native are deferred.
• Core does not own DOM, text direction, accessibility, or scrolling.
• Some state configurations use full recalculation.
• Reserved-region cost grows with obstacle workload.

한국어 문서로 전환 · MIT License

Acknowledgements

Embla Carousel, Swiper, and Keen Slider were evaluated as horizontal integration alternatives; they are not grid-masonry dependencies. Prior-art acknowledgement does not imply copied code, a fork, or endorsement. AI-assisted engineering tools supported implementation, testing, documentation, and review; human project ownership remains responsible for contracts and release decisions.