useMasonry
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.
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
API
Parameters
Input parameters accepted by this composable.
- optionsrequiredIUseMasonryOptions
- columnsRefrequiredRef<number>
- Default column count. Used when no breakpoint in breakpointsRef matches the container width.
- gapRefrequiredRef<number>
- Gap between items in pixels (both axes). The component resolves token/string gaps to a number before passing it here.
- breakpointsRefRef<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.
- alignRefRef<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
Responsive breakpoints