⚡ Powerful Image Grid for React

⚡Virtualized by Default 🔷 💡Multiple Layouts 🔷 🧱 Masonry Layout 🔷 🪶 Lightweight

• ⚡ Features
• 💭 How it works
• ⚙️ Installation
• 🧋 Usage
• 🍫 Props
• 🍭 Demo 1 (Horizontal)
• 🍭 Demo 2 (Vertical)
• ImageProps
• ImageSizes
• Theme
• 🧱 Masonry
• 🍫 Masonry Props
• ⛏️ Built Using
• ✍️ Authors
• 🤝Contributing
• Meta
• Meta
• Meta

⚡ Features

• 🪟 Generate grids easily.
• 🧱 Build beautiful Masonry grids using the Masonry component
• ➡️ Render images horizontally or vertically in a grid.
• ⚡ Built-in virtualization for improved performance.
• 🖼️ Load 1000's of images without worrying about performance.
• 🎛️ UI controls for adjusting image sizes.
• 💡 Resizable Grid
• 📦 Lightweight (7kb gzipped)
• 💪 Built with typescript.
• 💡 Intuitive API.

💭 How it works

react-visual-grid works with the absolute minimum of properties to determine the optimal method to render images. Specify the desired picture sizes and the layout, the component will automatically determine the optimum approach to rendering the images.

Comes with two different layouts (horizontal and vertical) for rendering images. The in-built virtualization ensures that the component renders only the images that are visible on the screen. This ensures that the component is able to render thousands of images without any performance issues.

Resize the grid or go full screen, and the component will automatically adjust the ideal number of images to be displayed in the new grid size.

In addition to the traditional grid, the library also comes with a masonry layout. The masonry layout is used to display images in a grid with varying heights/widths.

⚙️ Installation

You can install react-visual-grid using npm or yarn.

  npm install react-visual-grid

or

  yarn add react-visual-grid

🧋 Usage

Grids can be generated in two modes: Horizontal and Vertical. The default mode is vertical

import { Grid } from "react-visual-grid";

// generate random images using lorem picsum service
const images = Array.from({ length: 50 }, (_, i) => ({
  src: `https://picsum.photos/id/${Math.round(Math.random() * 110)}/800/600`,
  alt: `Image ${i + 1}`,
}));

const App = () => {
  return <Grid images={images} width={1800} height={1200} />;
};

The dimensions of the grid can be also specified as percentages.

import { Grid } from "react-visual-grid";

const App = () => {
  return <Grid images={images} width="90%" height="80%" />;
};

🍫 Props

Name	Description	Type	Default
enableResize	Allows the grid to be freely resized	boolean	true
enableDarkMode	Displays a toggle switch for switching between dark mode and default mode	boolean	false
gap	Gap in pixels between the images	number	20
gridLayout	Sets up the layout of the grid. can be horizontal or vertical	string	vertical
height	Height of the Grid	number or string	600
imageSizes	Configures the zoom sizes of the Images	Object	read more
images	Collection of Images to be rendered	ImageProps	[]
mode	Configures the rendering mode. can be auto or manual	string	auto
showProgressBar	Prop to show the progress bar	boolean	true
theme	Prop to apply different color scheme for the component	Object	read more
width	Width of the Grid	number or string	1200

🍭 Demo 1 (Horizontal)

import { Grid } from "react-visual-grid";

const App = () => {
  return (
    <Grid images={images} gridLayout="horizontal" width={1800} height={1200} />
  );
};

Horizontal Grid rendering 1k+ images

🍭 Demo 2 (Vertical)

import { Grid } from "react-visual-grid";

const App = () => {
  return (
    <Grid images={images} gridLayout="vertical" width={1800} height={1200} />
  );
};

Vertical Grid rendering 1k+ images

ImageProps

Name	Description	Type	Default
src	URL of the image	string
alt	Alt text for the image	string
width	Width of the image	number	100
height	Height of the image	number	100
id	Unique of the image	string
onClick	callback to be executed on click	Function

ImageSizes

react-visual-grid currently supports 3 zoom levels and the default level is 2x. The zoom levels can be configured using the imageSizes prop.

The component comes with a default configuration for the image sizes.

export const defaultImageSizes = {
  "1X": {
    width: 120,
    height: 100,
  },
  "2X": {
    width: 200,
    height: 180,
  },
  "3X": {
    width: 320,
    height: 280,
  },
};

you should be able to easily customize the desired dimensions for each zoom level.

Theme

Customize the colors of the component with the theme prop.

Here is the list of all the colors that can be customized:

Name	Description	Type	Default
primaryColor	Primary color of the gallery	string	#007fff
backgroundColor	Background color of the gallery	string	#000
controlBgColor	Background color of the control strip	string	#303030
controlBtnColor	Button color of the controls	string	#595959
controlsBackDropColor	Backdrop color of the controls	string	rgba(0, 0, 0, 0.95)
thumbnailBgColor	Background color of the Thumbnails	string	#202020

<Grid
  gridLayout="vertical"
  theme={{
    backgroundColor: "#000",
    controlBgColor: "#303030",
    controlBtnColor: "#595959",
    controlsBackDropColor: "rgba(0, 0, 0, 0.95)",
    thumbnailBgColor: "#202020",
  }}
/>

Custom Theme

🧱 Masonry

The masonry layout is an excellent option for showcasing images of varying sizes. With the Masonry component, you have the flexibility to arrange images either horizontally or vertically, and you can also define the dimensions of each image.

To set the height and width of each image, you'll use specific class names. For the width, use the format rc-w-[width], where [width] is replaced with the desired pixel value. Similarly, for the height, use rc-h-[height], replacing [height] with the corresponding value.

The layout adapts to the parent container's dimensions, ensuring that images are neatly wrapped to the next row or column based on the chosen fill mode. If you opt for vertical fill mode, the images will be organized into columns. Conversely, in horizontal fill mode, they will be arranged in rows.

const App = () => {
  const dimensions = [
    [400, 300],
    [950, 300],
    [450, 300],
    [700, 400],
    [500, 400],
    [600, 400],
    [1800, 250],
    [200, 350],
    [400, 350],
    [900, 350],
    [300, 350],
    [700, 200],
    [1100, 200],
  ];

  return (
    <Masonry
      animationDelay={500}
      fillMode="HORIZONTAL"
      gutter={0}
      height={1200}
      width={1800}
    >
      {dimensions.map(([w, h], index) => (
        <span className={`rc-w-${w} rc-h-${h}`} key={index}>
          <img
            alt="Image 1"
            src={`https://source.unsplash.com/random/${w}x${h}?space`}
          />
        </span>
      ))}
    </Masonry>
  );
};

Masonry CodeSandbox

🍫 Masonry Props

Name	Description	Type	Default
height	height of the grid	Number	1200
width	width of the grid	Number	800
enableAnimation	enable / disable the animation on load	Boolean	true
gutter	spacing between the images	Number	4
fillMode	prop that controls the filling direction. can be either HORIZONTAL or VERTICAL	String	4

⛏️ Built Using

• typescript
• react
• classNames

✍️ Authors

• @prabhuignoto - Idea & Initial work

🤝Contributing

1. Fork it
2. Create your feature branch (git checkout -b new-feature)
3. Commit your changes (git commit -am 'Add feature')
4. Push to the branch (git push origin new-feature)
5. Create a new Pull Request

Meta

Meta

Meta

Distributed under the MIT license. See LICENSE for more information.

Prabhu Murthy – @prabhumurthy2 – prabhu.m.murthy@gmail.com https://github.com/prabhuignoto