Masonry

Column-balancing masonry layout with SSR-deterministic distribution and optional virtualization.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { Masonry } from "@vizejs/ui/masonry";

Or copy the source into your project with vize lib pull masonry (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Photo wall balanced into three columns using estimated heights on the server. -->
<script setup lang="ts">
import { Masonry } from "@vizejs/ui/masonry";

interface Photo {
  readonly id: string;
  readonly caption: string;
  readonly height: number;
}

const photos: readonly Photo[] = [
  { id: "dunes", caption: "Dunes at dawn", height: 180 },
  { id: "harbor", caption: "Harbor lights", height: 120 },
  { id: "forest", caption: "Forest trail", height: 240 },
  { id: "glacier", caption: "Glacier edge", height: 150 },
  { id: "market", caption: "Night market", height: 200 },
];

function estimate(photo: Photo): number {
  return photo.height;
}

function keyOf(photo: Photo): string {
  return photo.id;
}
</script>

<template>
  <Masonry :items="photos" :columns="3" :gap="12" :estimate-height="estimate" :get-key="keyOf">
    <template #item="{ item }">
      <figure>
        <figcaption>{{ item.caption }}</figcaption>
      </figure>
    </template>
  </Masonry>
</template>

API

Masonry<Item>

Source: src/families/layout/masonry/masonry.vue

Props

Slots

Exposed

Behavior

Normative state x input -> outcome table for masonry.vue (@vizejs/ui/masonry). Rows are proven by masonry-layout.test.ts, masonry.test.ts, and masonry-ssr.test.ts; compile-only assertions live in masonry.types.test-d.ts.