VueCraft NPM

useMasonry Composable ​

useMasonry(container, options?) — the low-level escape hatch for when <MasonryGrid>'s slot-per-item layout doesn't fit. You own the item elements yourself; this only wires the engine to a container and keeps it in sync with reactive items.

ts
function useMasonry(
  container: MaybeRefOrGetter<HTMLElement | null | undefined>,
  options?: UseMasonryOptions,
): UseMasonryReturn

Creates the engine on mount and destroys it automatically on unmount.

Options ​

UseMasonryOptions extends MasonryOptions (see Engine API) with one extra reactive field:

items ​

MaybeRefOrGetter<RefFriendlyMasonryItem[]> · optional

RefFriendlyMasonryItem is core's MasonryItemDescriptor with el also accepting a Vue ref/getter, not just a plain element — an item whose el starts out null (its template ref hasn't mounted yet) syncs in automatically once it resolves. Omit this entirely to manage items yourself via engine.value.setItems(...).

Return value ​

engine ​

ShallowRef<MasonryEngine | null>

The engine instance (see Engine API) — null until the component mounts and container resolves to a real element. Use this for everything the reactive items option doesn't cover: addItem/removeItem/updateItem, relayout(), on(), or calling setItems yourself instead of passing the reactive option.

Example:

vue
<script setup lang="ts">
import { ref, computed } from 'vue'
import { useMasonry } from '@macrulez/masonry-kit-vue'

const containerEl = ref<HTMLElement | null>(null)
const cardAEl = ref<HTMLElement | null>(null)
const cardBEl = ref<HTMLElement | null>(null)

const items = computed(() => [
  { id: 'a', el: cardAEl },
  { id: 'b', el: cardBEl, colSpan: 2 },
])

const { engine } = useMasonry(containerEl, { items, columns: 'auto', minLaneSize: 240 })
</script>

<template>
  <div ref="containerEl">
    <div ref="cardAEl">A</div>
    <div ref="cardBEl">B</div>
  </div>
</template>