useMasonry

Masonry
stable

JavaScript fallback layout engine for OrigamMasonry when CSS grid-template-rows: masonry is unavailable. Implements a bucket-fill algorithm that places items into the shortest column, tracks container and item resize events via ResizeObserver, and exposes reactive per-item coordinates for inline-style assignment.

API

Signature

Full TypeScript signature sourced from the composable file.

typescript

useMasonry is the JS fallback path. OrigamMasonry first checks CSS.supports("grid-template-rows: masonry") and only activates this composable when that query returns false. The bucketFill and pickColumnsForWidth utilities are exported separately for unit testing.

Consumed interfaces

IUseMasonryOptions
IMasonryLayoutResult
IMasonryItemRect

API

Parameters

Input parameters accepted by this composable.

options
required
IUseMasonryOptions
columnsRef
required
Ref<number>
Default column count. Used when no breakpoint in breakpointsRef matches the container width.
gapRef
required
Ref<number>
Gap between items in pixels (both axes). The component resolves token/string gaps to a number before passing it here.
breakpointsRef
Ref<TMasonryColumnBreakpoints | undefined>
Optional map of container-width breakpoints to column counts (e.g. { 600: 2, 900: 3 }). The largest key that is less than or equal to the container width wins.
alignRef
Ref<TMasonryAlign>
'top'
Vertical alignment of items within a column. 'top' packs items to the top; 'center' distributes unused space above and below each column's content.

API

Return values

Properties and methods exposed by the composable return object.

containerRef
Bind this ref to the masonry container element. The composable installs a ResizeObserver on it to re-measure on width changes.
setItem
Register a child element by its render index. Call via :ref="(el) => setItem(idx, el)" on each masonry child. Idempotent — safe to call on updates.
layout
Reactive layout result containing containerHeight and an items array of per-item { left, top, width, height, column } descriptors. Apply as inline styles on each child.
relayout
Manual re-measure trigger. Call after async content changes (images loaded, fonts ready) that do not fire a ResizeObserver event.

Usage

Examples

Ready-to-paste usage snippets.

Basic masonry grid

vue

Responsive breakpoints

vue