Getting Started

Masonry Grid is a fast, lightweight, and responsive masonry grid layout library. This guide will help you get started with Masonry Grid in your project.

Installation

Vanilla JS

1. Install package by running the following command in your terminal:

   pnpm

   pnpm add @masonry-grid/vanilla

   Yarn

   yarn add @masonry-grid/vanilla

   npm

   npm install @masonry-grid/vanilla

   or use a CDN:

   import { BalancedMasonryGrid } from 'https://cdn.skypack.dev/@masonry-grid/vanilla'

2. Now you can import constructor and start using it in your project:

   HTML

   <div class="masonry">
     <!-- Each item must have aspect-ratio set by --width and --height CSS variables -->
     <div class="frame" style="--width: 4; --height: 3;">
       <img src="https://picsum.photos/400/300" />
     </div>
     <div class="frame" style="--width: 1; --height: 1;">
       <img src="https://picsum.photos/200/200" />
     </div>
     <div class="frame" style="--width: 3; --height: 4;">
       <img src="https://picsum.photos/300/400" />
     </div>
     <div class="frame" style="--width: 3; --height: 4;">
       <img src="https://picsum.photos/300/400" />
     </div>
     <div class="frame" style="--width: 1; --height: 1;">
       <img src="https://picsum.photos/200/200" />
     </div>
     <div class="frame" style="--width: 4; --height: 3;">
       <img src="https://picsum.photos/400/300" />
     </div>
   </div>

   CSS

   .masonry {
     /* Required styles */
     display: grid;
     overflow: hidden;
     /* Optional styles */
     gap: 10px;
     grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
   }
   
   .frame {
     /* Required styles */
     aspect-ratio: var(--width) / var(--height);
   }

   JS

   import { BalancedMasonryGrid } from '@masonry-grid/vanilla'
   
   new BalancedMasonryGrid(document.querySelector('.masonry'))

3. Run your application and see the masonry grid in action!

React

1. Install package by running the following command in your terminal:

   pnpm

   pnpm add @masonry-grid/react

   Yarn

   yarn add @masonry-grid/react

   npm

   npm install @masonry-grid/react

2. Now you can import the components and start using them in your React project:

   import { BalancedMasonryGrid, Frame } from '@masonry-grid/react'
   
   function Gallery() {
     return (
       <BalancedMasonryGrid
         frameWidth={200}
         gap={10}
       >
         <Frame width={4} height={3}>
           <img src='https://picsum.photos/400/300' alt='Photo 1' />
         </Frame>
         <Frame width={1} height={1}>
           <img src='https://picsum.photos/200/200' alt='Photo 2' />
         </Frame>
         <Frame width={3} height={4}>
           <img src='https://picsum.photos/300/400' alt='Photo 3' />
         </Frame>
         <Frame width={3} height={4}>
           <img src='https://picsum.photos/300/400' alt='Photo 4' />
         </Frame>
         <Frame width={1} height={1}>
           <img src='https://picsum.photos/200/200' alt='Photo 5' />
         </Frame>
         <Frame width={4} height={3}>
           <img src='https://picsum.photos/400/300' alt='Photo 6' />
         </Frame>
       </BalancedMasonryGrid>
     )
   }

3. Run your React application and see the masonry grid in action!

Svelte

1. Install package by running the following command in your terminal:

   pnpm

   pnpm add @masonry-grid/svelte

   Yarn

   yarn add @masonry-grid/svelte

   npm

   npm install @masonry-grid/svelte

2. Now you can import the components and start using them in your Svelte project:

   <script>
     import { BalancedMasonryGrid, Frame } from '@masonry-grid/svelte'
   </script>
   
   <BalancedMasonryGrid
     frameWidth={200}
     gap={10}
   >
     <Frame width={4} height={3}>
       <img src='https://picsum.photos/400/300' alt='Photo 1' />
     </Frame>
     <Frame width={1} height={1}>
       <img src='https://picsum.photos/200/200' alt='Photo 2' />
     </Frame>
     <Frame width={3} height={4}>
       <img src='https://picsum.photos/300/400' alt='Photo 3' />
     </Frame>
     <Frame width={3} height={4}>
       <img src='https://picsum.photos/300/400' alt='Photo 4' />
     </Frame>
     <Frame width={1} height={1}>
       <img src='https://picsum.photos/200/200' alt='Photo 5' />
     </Frame>
     <Frame width={4} height={3}>
       <img src='https://picsum.photos/400/300' alt='Photo 6' />
     </Frame>
   </BalancedMasonryGrid>

3. Run your Svelte application and see the masonry grid in action!