Masonry

Layout & Structure
stable

Pinterest-style masonry grid. Uses native CSS grid-template-rows: masonry when supported; falls back to a ResizeObserver bucket-fill algorithm. Container-query responsive via columnBreakpoints.

Structure

Anatomie

Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.

Anatomy of OrigamMasonrySchematic of the Masonry component in CSS and JS fallback paths. CSS path (grid-template-rows: masonry) JS fallback (ResizeObserver + bucket-fill) __item 1 2 3 4 CSS path: display: grid + masonry / JS path: position: absolute per item
Anatomy of <origam-masonry> — ① CSS path (grid-template-rows: masonry, native, no wrappers), ② JS fallback path (position: relative container), ③ direct child (CSS path — no wrapper), ④ .origam-masonry__item (JS path — absolute wrapper added by the component).
1.origam-masonry.origam-masonry--css
CSS path: display: grid; grid-template-rows: masonry; align-tracks: start. grid-template-columns set via --origam-masonry---template-columns CSS var. No item wrappers — children are direct grid items.
2.origam-masonry.origam-masonry--js
JS fallback path: position: relative; display: block. Container height driven by --origam-masonry---container-height. Items absolutely positioned.
3(direct child — CSS path)
In the CSS path, children are placed directly as grid items. No wrapper is injected by the component.
4.origam-masonry__item
In the JS fallback path, each child VNode is wrapped in a div.origam-masonry__item with position: absolute; left/top/width computed by useMasonry.

API

Props

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.

columns
number
3
Default number of columns when no columnBreakpoints entry matches the container width. Must be a positive integer ≥ 1.
columnBreakpoints
Map of min-width (px) → column count. Based on container width (not viewport) via ResizeObserver. Example: { 600: 2, 900: 3, 1200: 4 }.
Gap between items. Accepts a token size key (xs | sm | md | lg | xl), a CSS length string, or a number (→ px). Defaults to md.
animated
boolean
true
Animates item position changes (transform, top, left, width) when the column count changes. Uses CSS transition — disabled under prefers-reduced-motion.
align
'top'
Vertical alignment of items. "top" (standard Pinterest layout) | "center". Only the JS fallback honours "center" — the CSS path always packs to the top.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
tag
string
'div'
Root HTML element tag.
height
number | string
Fixed height of the masonry container.
maxHeight
number | string
maxWidth
number | string
minHeight
number | string
minWidth
number | string
width
number | string
Fixed width of the masonry container.
margin
boolean | number | string
marginTop
boolean | number | string
marginLeft
boolean | number | string
marginBottom
boolean | number | string
marginRight
boolean | number | string
marginBlock
boolean | number | string
marginInline
boolean | number | string
marginInlineStart
boolean | number | string
marginInlineEnd
boolean | number | string
marginBlockStart
boolean | number | string
marginBlockEnd
boolean | number | string
padding
boolean | number | string
paddingTop
boolean | number | string
paddingLeft
boolean | number | string
paddingBottom
boolean | number | string
paddingRight
boolean | number | string
paddingBlock
boolean | number | string
paddingInline
boolean | number | string
paddingInlineStart
boolean | number | string
paddingInlineEnd
boolean | number | string
paddingBlockStart
boolean | number | string
paddingBlockEnd
boolean | number | string
Border-radius token or boolean.
roundedTopRight
boolean | number | string
roundedTopLeft
boolean | number | string
roundedBottomLeft
boolean | number | string
roundedBottomRight
boolean | number | string
roundedStartStart
boolean | number | string
roundedStartEnd
boolean | number | string
roundedEndStart
boolean | number | string
roundedEndEnd
boolean | number | string
elevation
TElevation
Box-shadow elevation token.
bgColor
Background color of the masonry container.
color
Foreground color inherited by children.
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
false
Applies a border to the container.
borderTop
boolean | number | string
borderLeft
boolean | number | string
borderBottom
boolean | number | string
borderRight
boolean | number | string
borderBlock
boolean | number | string
borderInline
boolean | number | string
borderInlineStart
boolean | number | string
borderInlineEnd
boolean | number | string
borderBlockStart
boolean | number | string
borderBlockEnd
boolean | number | string
borderColor
string
borderStyle
string
borderTopColor
TColor
borderRightColor
TColor
borderBottomColor
TColor
borderLeftColor
TColor
borderInlineStartColor
TColor
borderInlineEndColor
TColor
borderBlockStartColor
TColor
borderBlockEndColor
TColor

API

Slots

Emplacements de contenu exposés par ce composant.

#default
Children to layout in the masonry grid. Each direct child is treated as a masonry item. In the JS fallback path, each child is wrapped in a div.origam-masonry__item with absolute positioning.

API

Membres exposés

Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.

<T extends object>(props: T, exclude?: string[]) => Partial<T>
Utility to forward a filtered subset of props to a child.
Ref<{ items: Array<{ left: number; top: number; width: number }>; containerHeight: number }>
Reactive layout data computed by useMasonry. Available in both paths but only consumed by the template in the JS path.
() => void
Forces an immediate re-computation of the bucket-fill layout. Useful after programmatically changing item content without changing the DOM structure.
ComputedRef<boolean>
True when the CSS masonry path is active. False when the JS fallback runs.
Ref<number>
Current gap value in pixels as resolved by getComputedStyle. Used by the JS bucket-fill algorithm.

Personnalisation

Variables CSS

Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.

Bridge variable: the serialised gap value (token or raw CSS). Consumed by the gap property AND read back by the JS algo via getComputedStyle.
CSS path only. Set to repeat(N, 1fr) where N = active column count.
JS path only. Set to the computed total height of the bucket-fill layout.
Duration of position-change transitions (animated=true).
Easing of position-change transitions.

Inclusion

Accessibilité

Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.

Rôles ARIA

list

Notes

  • OrigamMasonry renders with <code>role="list"</code>. In the JS path, each item wrapper carries <code>role="listitem"</code>. In the CSS path, direct children should carry their own semantic markup.
  • Items are laid out in DOM order. Visual column order may differ from reading order — ensure the DOM order matches a meaningful reading sequence for keyboard and screen reader users.
  • Transitions are disabled under <code>prefers-reduced-motion: reduce</code> via a dedicated @media block in the SCSS.

Fondation

Design tokens

Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.

Source
duration
var(--origam-motion__duration---fast)
Duration of the animated position-change transition.
cubicBezier
var(--origam-motion__easing---standard)
Easing of the animated position-change transition.

Interactif

Playground

Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.

Rendu de l’aperçu en cours…

Usage

Exemples

Extraits de code prêts à coller dans vos templates.

Basic masonry

vue

Container-query breakpoints

vue

With animation disabled

vue