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

Anatomy

Visual breakdown of the component's internal structure with BEM class call-outs.

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

All props accepted by this component, with their type, default value and 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

Content slots exposed by this component.

#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

Exposed members

Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.

<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.

Customisation

CSS variables

CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.

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

Accessibility

ARIA roles, keyboard navigation and focus management. Sourced from the real component template.

ARIA roles

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.

Foundation

Design tokens

Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.

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.

Interactive

Playground

Edit props live and see the component update in real time. The generated code snippet updates as you change values.

Rendering the live preview…

Usage

Examples

Ready-to-paste code snippets for your templates.

Basic masonry

vue

Container-query breakpoints

vue

With animation disabled

vue