pnpm add -D svelte-bricks

The kitchen sink for this component looks something like this:

<script>
  import Masonry from 'svelte-bricks'

  let nItems = $state(30);
  let items = $derived([...Array(nItems).keys()])

  let [minColWidth, maxColWidth, gap] = [200, 800, 20]
  let width = $state(0), height = $state(0)
</script>

Masonry size: <span>{width}px</span> &times; <span>{height}px</span> (w &times; h)

<Masonry
  {items}
  {minColWidth}
  {maxColWidth}
  {gap}
  style="padding: 20px;"
  columnStyle="background-color: rgba(0, 0, 0, 0.1);"
  bind:masonryWidth={width}
  bind:masonryHeight={height}
>
  {#snippet children({ item })}
    <Some {item} />
  {/snippet}
</Masonry>

Note: If items is an array of objects, this component tries to access an id property on each item. This value is used to tell items apart in the keyed {#each} block that creates the masonry layout. Without it, Svelte could not avoid duplicates when new items are added or existing ones rearranged. Read the Svelte docs for details. To change the name of the identifier key, pass idKey="some-uniq-key. Or pass a function getId = (item: Item) => string | number that maps items to unique IDs.

Masonry.svelte expects an array of items as well as a <slot /> component used to render each of the items. The array can contain whatever data (objects, strings, numbers) as long as the slot component knows how to handle it.

Additional optional props are:

1. animate: boolean = true

   Whether to FLIP-animate masonry items when viewport resizing or other events cause items to rearrange.

2. order: 'balanced' | 'balanced-stable' | 'row-first' | 'column-sequential' | 'column-balanced' = 'balanced'

   Controls how items are distributed across columns:

   • balanced (default): Items are placed in the shortest column for optimal visual balance. Items may jump between columns when the list changes.
   • balanced-stable: Like balanced, but existing items never move. New items go to the shortest column. Ideal for infinite scroll.
   • row-first: Round-robin distribution (1→2→3→1→2→3...). Predictable row-major order.
   • column-sequential: Fills columns sequentially (first N items in column 1, next N in column 2, etc.). Strict column-major order.
   • column-balanced: Height-aware column-first. Fills column 1 until it reaches target height, then column 2, etc. Maintains reading order while balancing heights.

3. calcCols = (
     masonryWidth: number,
     minColWidth: number,
     gap: number,
   ): number => {
     return Math.min(
       items.length,
       Math.floor((masonryWidth + gap) / (minColWidth + gap)) || 1,
     )
   }

   Function used to compute the number of columns based on the masonry width, minimum column width and gap.

4. class: string = ``

   Applies to the outer div wrapping all masonry columns. For use with CSS frameworks like Tailwind.

5. columnClass: string = ``

   Applies to each column div.

6. duration: number = 200

   Transition duration in milli seconds when masonry items are rearranged or added/removed. Set to 0 to disable transitions.

7. gap: number = 20

   Gap between columns and items within each column in px.

8. getId = (item: Item): string | number => {
     if (typeof item === `number`) return item
     if (typeof item === `string`) return item
     return item[idKey]
   }

   Custom function that maps masonry items to unique IDs of type string or number.

9. idKey: string = `id`

   Name of the attribute to use as identifier if items are objects.

10. items: Item[]

    The only required prop is the list of items to render where Item is a generic type (via generics="Item") which usually will be object but can also be simple types string or number.

11. masonryHeight: number = 0

    The masonry divs height in px.

12. masonryWidth: number = 0

    The masonry divs width in px.

13. maxColWidth: number = 500

    Maximum column width in px.

14. minColWidth: number = 330

    Minimum column width in px.

15. style: string = ``

    Inline styles that will be applied to the top-level div.masonry.

For large lists (1000+ items), enable virtual scrolling to render only visible items:

<Masonry
  {items}
  virtualize={true}
  height={600}
  getEstimatedHeight={(item) => item.height ?? 150}
  overscan={5}
>
  {#snippet children({ item })}
    <Card {item} />
  {/snippet}
</Masonry>

1. virtualize: boolean = false

   Enable virtual scrolling. When true, only visible items are rendered. Requires the height prop.

2. height: number | string

   Required when virtualize=true. Sets the scroll container height (e.g., 500 for pixels or "80vh").

3. getEstimatedHeight?: (item: Item) => number

   Optional function that returns an estimated height for items before they're measured. Defaults to 150px if not provided. Better estimates = less layout shift.

4. overscan: number = 5

   Number of items to render above and below the visible area. Higher values reduce flicker during fast scrolling but render more items.

Notes:

• FLIP animations are automatically disabled when virtualizing
• Virtualization forces row-first order mode for stability
• Height-dependent order modes (balanced, balanced-stable, column-balanced) use estimated heights until items are measured
• The masonry div becomes a scroll container (overflow-y: auto)

Besides inline CSS which you can apply through the style prop, the following :global() CSS selectors can be used for fine-grained control of wrapper and column styles:

:global(div.masonry) {
  /* top-level wrapper div */
}
:global(div.masonry div.col) {
  /* each column in the masonry layout */
}