Masonry

Masonry uses CSS Grid to create a masonry layout.

It is supported natively by Firefox; we polyfilled this behaviour with a little bit of JavaScript for other browsers.

Create Masonry layouts with CSS Grid

Just specify the number of columns and you’re good to go.

<div class="Masonry [--cols:2]">
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

Span multiple columns

You can span an item across multiple columns with the --span property. (No other Masonry layouts on the internet lets you do this so easily).

<div class="Masonry">
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div class="[--span:2]">...</div>
  <div>...</div>
</div>

Dense supported

Since we use CSS Grid, you can also use dense to pack smaller items upwards.

<div class="Masonry [--cols:3] dense">
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

Make it responsive easily

Like SimpleGrid, you just have to change the --cols property at different breakpoints to make a responsive Masonry layout.

<div class="Masonry md:[--cols:2] lg:[--cols:3]">
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

Resize to see this work!

Item-sizing supported

Instead of using --cols to determine the number of columns, you can let CSS Grid create intrinsic columns with Masonry-gallery and --item-width.

<div class="Masonry-gallery [--item-width:5rem] dense">
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

Resize to see this work!

Waits for images and videos to load

Masonry waits for images and videos to load before it calculates the layout. This ensures your layout is accurate regardless of the content you contained within each grid item.

Installation

Masonry requires JavaScript for cross-browser support. To use Masonry, you need to import and run the Masonry script.

import { Masonry } from '@splendidlabz/layouts/scripts'
Masonry()

More information about this script can be found in the Masonry Script section.

Basic Usage

Masonry’s API is similar to SimpleGrid. You can define the number of columns in your Masonry grid with --cols.

<div class="Masonry [--cols:2]">
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

Spanning Multiple items

You can span an item across multiple columns with the --span property.

<div class="Masonry [--cols:3]">
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div class="[--span:2]">...</div>
  <div>...</div>
</div>

Dense

You can use dense to pack smaller items into the empty spaces left by larger items.

<div class="Masonry [--cols:3]">
  <div>...</div>
  <div>...</div>
  <div class="[--span:2]">...</div>
  <div>...</div>
  <div>...</div>
</div>

<div class="Masonry [--cols:3] dense">
  <div>...</div>
  <div>...</div>
  <div class="[--span:2]">...</div>
  <div>...</div>
  <div>...</div>
</div>

Gap between grid items

You can change the gap between items with the gap property or the --gap variable. Row gaps cannot be adjusted independently from the column gap.

<div class="Masonry [--cols:2] gap-8">
  <div>...</div>
  <div>...</div>
</div>

<div class="Masonry" style="--cols:2; --gap:2rem">
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

Responsive Behaviour

You can change --cols at different breakpoints to make your Masonry Grid behave responsively.

<div class="Masonry md:[--cols:2] lg:[--cols:3]">
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

Masonry Gallery

Masonry has gallery modifier that lets you determine the size of each column with the --item-width property. --cols has no effect if you use this.

<div class="Masonry-gallery [--item-width:10rem] dense">
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

The Masonry Script

Searching in a specific container

By default, the Masonry script searches the DOM for any Masonry layouts. If you wish to search for Masonry in a specific container, you can pass an element or a selector into the script.

import { Masonry } from '@splendidlabz/layouts/scripts'
const container = document.querySelector('.container')
Masonry(container)

import { Masonry } from '@splendidlabz/layouts/scripts'
Masonry('.container')

Async containers

The Masonry script doesn’t scan the DOM for new Masonry grids after it has been loaded. So if you create a Masonry grid after the script has been called, it won’t be picked up.

To initialize your new Masonry grid, just call the Masonry script again (preferably with the container as an argument).

Waiting for Images and Videos to Load

The Masonry script waits for images and videos to load before calculating layouts. This ensures your layout is accurate regardless of the content it holds.

<div class="Masonry [--cols:3] dense">
  <div> <img src="..." /> </div>
  <div> <img src="..." /> </div>
  <div> <img src="..." /> </div>
  <div> <img src="..." /> </div>
  <div> <img src="..." /> </div>
</div>

Note

Masonry is unable to prevent Cumulative Layout Shift (CLS) because it doesn’t know the dimensions of the media elements before they load.

To prevent CLS, just provide width and height attributes to your media elements before they load. You can find more information about CLS prevention in our Astro Image component

Resize Observer

The Masonry script uses a resizeObserver to detect changes in the layouts. So Masonry will run whenever the container resizes, or when you add items into the container. No need to worry about responsive layouts!

Please login to view this content

Splendid Labz is free because we love developers and we want to contribute back to the ecosystem.

We only charge for access to the documentation to keep the project going. If you don't wish to pay, feel free to use the content from the features tab, our blogs or our videos as your guide.

Here’s the CSS for Masonry.

The astro-island and astro-slot selectors help to alleviate styling frustrations when using Astro.

[class*='Masonry'] {
  display: grid;
  grid-template-columns: repeat(var(--cols, 1), minmax(0, auto));
  grid-template-rows: masonry;
  gap: var(--gap, 1rem);

  > *,
  > :where(astro-slot, astro-island) > * {
    align-self: start;
    max-width: 100%;
    grid-column-end: span var(--span, 1);
  }
}

.Masonry-gallery {
  grid-template-columns: repeat(
    auto-fill,
    minmax(min(var(--item-width, 3rem), 100%), 1fr)
  );
}

Please login to view this content

Splendid Labz is free because we love developers and we want to contribute back to the ecosystem.

We only charge for access to the documentation to keep the project going. If you don't wish to pay, feel free to use the content from the features tab, our blogs or our videos as your guide.

Masonry

Modifiers

Class	Description
`Masonry-gallery`	Creates a Gallery-like masonry layout where you size columns with `--item-width`.

CSS Variables

CSS Variable	Default	Description
`--gap`	`1rem`	Gap between columns
`--cols`	`1`	Number of columns. Used in `Masonry` only
`--item-width`	`3rem`	Size of each column. Used in `Masonry-gallery` only

Children

CSS Variables

CSS Variable	Default	Description
`--span`	`1`	Number of columns that the child should occupy.

Masonry Script

Props	Default	Description
`selector`	`undefined`	The container for the script. You can pass a `selector` or `element` into this value. When `undefined`, it defaults to `document.body`.

Please login to view this content

Splendid Labz is free because we love developers and we want to contribute back to the ecosystem.

We only charge for access to the documentation to keep the project going. If you don't wish to pay, feel free to use the content from the features tab, our blogs or our videos as your guide.