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
Signature TypeScript complète extraite du fichier du composable.
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.
Interfaces consommées
API
Paramètres
Paramètres d'entrée acceptés par ce composable.
- optionsrequisIUseMasonryOptions
- columnsRefrequisRef<number>
- Default column count. Used when no breakpoint in breakpointsRef matches the container width.
- gapRefrequisRef<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
Valeurs de retour
Propriétés et méthodes exposées par l'objet retourné par le composable.
- 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
Exemples
Extraits de code prêts à coller.
Basic masonry grid
Responsive breakpoints