Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

react-visual-grid logo

Status License codebeat badge CodeFactor npm bundle size Known Vulnerabilities Follow on Twitter

⚑ Powerful Image Grid for React

⚑Virtualized by Default πŸ”· πŸ’‘Multiple Layouts πŸ”· 🧱 Masonry Layout πŸ”· πŸͺΆ Lightweight

⚑ 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


  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: `${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


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


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.


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
    backgroundColor: "#000",
    controlBgColor: "#303030",
    controlBtnColor: "#595959",
    controlsBackDropColor: "rgba(0, 0, 0, 0.95)",
    thumbnailBgColor: "#202020",

Custom Theme

🧱 Masonry

The masonry layout is a great choice for displaying images of different sizes. You can choose to fill the images horizontally or vertically, and choose how big you want them to be. The Masonry component sets the height and width of each image using class names. Class names should be formatted rc-w-[width], where [width] corresponds to an integer length value measured in pixels; similarly, class names should be formatted rc-h-[height], with correspondingly formatted values.

The layout honors the dimensions of the parent container, and the images will be automatically wrapped to the next row or column depending on the fill mode. In vertical fill mode, the images are arranged in columns, and in horizontal fill mode, the images are arranged in rows.

The Masonry Component exports as its own React Component, with documentation available at the following URL

<Masonry fillMode="HORIZONTAL" height={1200} width={300}>
  <span className={`rc-w-100 rc-h-100`}>
    <img alt="Image 1" src={``} />
  <span className={`rc-w-200 rc-h-100`}>
    <img alt="Image 1" src={``} />
  <span className={`rc-w-200 rc-h-100`}>
    <img alt="Image 1" src={``} />
  <span className={`rc-w-100 rc-h-100`}>
    <img alt="Image 1" src={``} />
  <span className={`rc-w-300 rc-h-150`}>
    <img alt="Image 1" src={``} />


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

✍️ Authors


  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




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

Prabhu Murthy – @prabhumurthy2 –