1.2.2 • Published 5 months ago

astro-masonry v1.2.2

Weekly downloads
-
License
MIT
Repository
github
Last release
5 months ago

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

PropTypeDefaultDescription
breakpointColsnumber \| Record<number \| "default", number>2Number of columns at different breakpoints
classstring"astro-masonry-grid"CSS class for the container
columnClassstring"astro-masonry-grid_column"CSS class for columns
sortByHeightbooleanfalseSort items by height for balanced layout
debugbooleanfalseEnable 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

1.2.2

5 months ago

1.2.1

5 months ago

1.2.0

5 months ago

1.1.1

5 months ago

1.1.0

5 months ago

1.0.3

6 months ago

1.0.2

7 months ago

1.0.1

7 months ago

1.0.0

7 months ago