Masonry

masonry uses CSS Grid to create a masonry layout that is supported natively by Firefox. Then, we polyfilled this behaviour with a little bit of JavaScript to make it work in other browsers.

Create masonry layouts with CSS Grid

Just specify the number of columns and we’ll take care of the rest.

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

Allow grid items span different 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).

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>

Make it responsive easily

Like grid-simple, 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.

Resize to see this work!

Automatically 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 so 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 grid-simple. 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] 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>

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-gallery lets you 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 script does not detect classes after it has been loaded. If you add a masonry class to an element after the script has been loaded, it won’t be picked up.

To pick it up, you have to call the script again.

Automatically 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 will not be able to prevent Cumulative Layout Shift (CLS) automatically since it doesn’t know the dimensions of the media elements within them.

To prevent CLS, you can 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 purchase a license to view this content

This content is part of our premium documentation. To access it, you'll need to have an active license for one of these products.

Get Layouts Get Basic Get Pro

If you already have a license, please login to access this content.

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

.masonry {
  display: grid;
  grid-template-columns: repeat(var(--cols, 1), minmax(0, auto));
  gap: var(--gap-y, var(--gap)) var(--gap-x, var(--gap));
  max-width: 100%;
  grid-template-rows: masonry;

  > *,
  > *:where(.contents) > *,
  > *:where(astro-island, astro-slot) > * {
    grid-column-end: span var(--span, 1);
    align-self: start;
  }
}

.masonry-gallery {
  display: grid;
  grid-template-columns: repeat(
    grid-template-rows: masonry; auto-fill,
    minmax(min(var(--item-width, 3rem), 100%), 1fr)
  );
  gap: var(--gap-y, var(--gap)) var(--gap-x, var(--gap));
  max-width: 100%;

  > *,
  > *:where(.contents) > *,
  > *:where(astro-island, astro-slot) > * {
    grid-column-end: span var(--span, 1);
    align-self: start;
  }
}

Please purchase a license to view this content

This content is part of our premium documentation. To access it, you'll need to have an active license for one of these products.

Get Layouts Get Basic Get Pro

If you already have a license, please login to access this content.

Masonry

Class modifiers

Class	Description
`masonry-gallery`	Lets you size items with `--item-width`, as if you’re using `grid-gallery`.

CSS Variables

CSS Variable	Default	Description
`--gap-x`	-	Gap between columns
`--gap-y`	-	Gap between rows
`--gap`	`1rlh`	Gap between columms and rows. `--gap-x` and `--gap-y` will override this value.
`--cols`	`1`	Number of columns
`--item-width`	`3rem`	Size of each column. Used in `gallery-masonry` 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 purchase a license to view this content

This content is part of our premium documentation. To access it, you'll need to have an active license for one of these products.

Get Layouts Get Basic Get Pro

If you already have a license, please login to access this content.