Want to create responsive waterfall grid layouts in React? Creating such layouts that auto-adapt to dynamic element sizes and is responsive, is quite difficult. Certain packages make it possible, but it can get complicated.

What if I can provide you a one-liner solution?

Introduction

“One line? What!”

Well, yes! I had been learning React since a few months now, and it was while working on a personal project, which needed a grid layout that could auto-adjust its grids, that I saw that although there are packages that help with these, they are too complicated.

So, I thought up a way, and created my first npm package for React — react-waterfall-grid !

“So how does it help me?”

1<WaterfallGrid childWidth={300} styleGridContainer={{ width: "100%", position: "relative", justifyContent: "center", zIndex: 1 }}>
2    {imagesList}
3</WaterfallGrid>

See that one liner code? That’s a fully responsive, auto-adjusting waterfall grid!

Wanna see a live demo? See this.

How does it work?

React-Waterfall-Grid is a library of fully responsive and customizable waterfall grids (vertical and horizontal). All it needs is an array of your elements, and it handles the rest out-of-the-box.

At its core, react-waterfall-grid uses flexbox to place items correctly. So, all the possible props that you can pass to the Grid components (see 'All Grids') are the same as what you would pass to flexbox. The below example will show you how it's done.

Quickstart

Here's a small example to get you started. Take note of how the array of (one-dimensional) elements is passed to the grid through a prop. Yes, you pass all your stuff only once, and all subsequent layout changes are handled automatically!

1import styled from 'styled-components'
2import {WaterfallGrid} from 'react-waterfall-grid'
3import { useMediaQuery } from 'react-responsive'
4// You are free to add as many grid contents as you want. Here, you see only 4 pictures.
5import Image1 from './static/images/1.jpg'
6import Image2 from './static/images/2.jpg'
7import Image3 from './static/images/3.jpg'
8import Image4 from './static/images/4.jpg'
9const ParentContainer = styled.div`
10  width: 100%;
11  background-color: #121212;
12`
13const Image = styled.img`
14  object-fit: cover;
15`
16export default function App() {
17  // Boolean - True if phone
18  const isPhone = useMediaQuery({ query: 'max-width: 480px' })
19  // List of images <img>
20  const imagesList = [Image1, Image2, Image3, Image4].map((imagePath) => (
21    <Image key={imagePath} style={{ width: (isPhone ? "200px" : "300px") }} src={imagePath} alt={imagePath}
22      variants={imageVariants} whileHover={{ scale: 1.05, transition: { ease: ease, duration: 0.8 } }} />
23  ))
24  return (
25    <ParentContainer id="parent-container">
26      <WaterfallGrid childItems={imagesList} childWidth={isPhone ? 200 : 300}
27        styleGridContainer={{ width: "100%", position: "relative", justifyContent: "center", zIndex: 1 }}/>
28    </ParentContainer>
29  );
30}

Features

With react-waterfall-grid, you get access to two different grid containers -

• WaterfallGrid

• WaterfallHorizontalGrid

As you might have guessed, WaterfallGrid is named so because the child contents fall vertically, while in WaterfallHorizontalGrid the child contents 'fall' horizontally.

The vertical grid will only accept child elements with a fixed width but any height. (to keep the elements' layout changes constrained), whereas the horizontal grid will only accept child elements with a fixed height but any width.

Based on this, there are different props, some common to both Grids, and the rest are specific to a particular type of Grid.

Lastly, react-waterfall-grid uses flexbox at its core, so to customize styles for the grid container as a whole or the grid columns (or rows, for horizontal grids), pass in the style with the appropriate prop just like you would for a native flexbox container.

"Looks great! How do I get it?"

As with all npm packages, you download the package like so:

npm install --save react-waterfall-grid

Read the documentation for knowing all that you can do.

Ending note

react-waterfall-grid is built keeping the need of simplicity in mind. It helps you quickly create beautiful grids that can manage themselves!

Give it a try, and tell me how you use it in your projects!