Masonry
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.
<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-columnsset via--origam-masonry---template-columnsCSS 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__itemwithposition: absolute; left/top/widthcomputed by useMasonry.
API
Props
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.
- columnsnumber3
- 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.
- animatedbooleantrue
- Animates item position changes (transform, top, left, width) when the column count changes. Uses CSS transition — disabled under prefers-reduced-motion.
- Vertical alignment of items. "top" (standard Pinterest layout) | "center". Only the JS fallback honours "center" — the CSS path always packs to the top.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- tagstring'div'
- Root HTML element tag.
- heightnumber | string
- Fixed height of the masonry container.
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- Fixed width of the masonry container.
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- Border-radius token or boolean.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- elevationTElevation
- Box-shadow elevation token.
- bgColor
- Background color of the masonry container.
- color
- Foreground color inherited by children.
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Applies a border to the container.
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
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
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.
- durationvar(--origam-motion__duration---fast)
- Duration of the animated position-change transition.
- cubicBeziervar(--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
Container-query breakpoints
With animation disabled