Astro Masonry

A zero-dependency responsive masonry layout component for Astro with minimal setup.

• Zero setup required: Works out of the box
• Fully responsive: Configure columns for any breakpoint
• View Transitions: Support for Astro’s built-in transitions
• Highly customizable: Apply custom classes to container and columns
• Zero dependencies: Pure vanilla JavaScript
• Minimal client JS: Small runtime footprint
• Performance-first: Optimized for speed and efficiency
• Lazy Loading: Supports Astro's lazy-loading features

Demo

Motivation

Most masonry layout libraries are either JavaScript-heavy or framework-dependent, making them suboptimal for Astro. This Astro-native component stays within the Astro ecosystem (avoiding unnecessary frameworks) and works seamlessly with Astro's <Image/> component, providing built-in image optimization and preventing Cumulative Layout Shift (CLS).

Installation

npm install astro-masonry

Usage

---
import { Masonry } from 'astro-masonry';
---

<Masonry
  breakpointCols={{
    default: 4,
    1100: 3,
    700: 2,
    500: 1
  }}
>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Masonry>

Props

Prop	Type	Default	Description
breakpointCols	number | Record<number | "default", number>	2	Number of columns at different breakpoints
class	string	"astro-masonry-grid"	CSS class for the container
columnClass	string	"astro-masonry-grid_column"	CSS class for columns
sortByHeight	boolean	false	Sort items by height for balanced layout
debug	boolean	false	Enable console logging of the masonry component events

Breakpoints

You can specify different column counts for different screen widths:

{
  default: 4, // Default column count
  1100: 3,    // 3 columns at viewport width <= 1100px
  700: 2,     // 2 columns at viewport width <= 700px
  500: 1      // 1 column at viewport width <= 500px
}

Styling

The component includes minimal styling for the grid layout. You can customize the appearance by overriding the default classes:

.astro-masonry-grid {
  /* Your custom styles */
  /* You will need to add display: flex */
}

.astro-masonry-grid_column {
  /* Your custom column styles */
}

Alternatively, you can apply custom classes directly on the component. This is very useful if you use Tailwind.

<Masonry
  breakpointCols={3}
  class="flex gap-4 px-4"
  columnClass=""
>
</Masonry>

Height-based Sorting

Enable sortByHeight to create a more balanced layout by placing items in the column with the least height

⚠️ Note: This option breaks the original items order to achieve a more balanced layout height distribution.

<Masonry
  ...
  sortByHeight={true}
>
</Masonry>

Lazy Loading

Depending on how you're loading your images you'll need to configure a few things to ensure seamless lazy loading with this component.

Local images

For local images, set the width property and loading="lazy" on the <Image /> component. Astro will handle the rest.

Remote images

1. Ensure your authorizing remote images from the images domain. See Astro - Authorizing remote images for more information.
2. Apply inferSize and loading="lazy" to the component. inferSize is crucial for preventing layout shift with remote images.

Example

---
import { Masonry } from "../../../src/index";
import { Image } from "astro:assets";
---

<Masonry
  breakpointCols={{
    default: 4,
    1200: 3,
    700: 2,
    500: 1,
  }}
  class="flex gap-4 px-4"
  columnClass=""
>
  {
    [...Array(40)].map((_, i) => (
      <Image
        src={`https://picsum.photos/1200/${Math.floor(Math.random() * (1200 - 600 + 1) + 600)}`}
        alt=""
        inferSize
        class="w-full mb-4"
      />
    ))
  }
</Masonry>

Credits

This component is heavily inspired by react-masonry-css, essentially serving as an Astro-native port that brings the same elegant simplicity.

License

MIT © Olivier Estévez