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
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<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
All props accepted by this component, with their type, default value and 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
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
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.
- durationvar(--origam-motion__duration---fast)
- Duration of the animated position-change transition.
- cubicBeziervar(--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
Container-query breakpoints
With animation disabled