# react-visual-grid > Highly configurable virtualized image gallery for React Latest version **0.9.5** (published 2023-08-21) · MIT license · 0 weekly downloads ## Install ```sh npm install react-visual-grid pnpm add react-visual-grid yarn add react-visual-grid bun add react-visual-grid ``` ## Health **Score 20/100 (F)** — status: abandoned. Positive: esm support; no vulnerabilities. Warnings: low downloads; no types; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.9.5 | | Published | 2023-08-21 | | First published | 2022-11-22 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | ESM + CommonJS | | Dependencies | 2 | | Unpacked size | 124.9 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 154 | | Author | Prabhu Murthy | | Maintainers | prabhuignoto | | Keywords | images, gallery, virtualized, virtualized images, react images, react gallery | ## Links - npm: https://www.npmjs.com/package/react-visual-grid - Repository: https://github.com/prabhuignoto/react-visual-grid - Homepage: https://github.com/prabhuignoto/react-visual-grid#readme - Issues: https://github.com/prabhuignoto/react-visual-grid/issues - npm.io page: https://npm.io/package/react-visual-grid ## Dependencies (2) - [classnames](https://npm.io/package/classnames.md) ^2.3.2 - [use-debounce](https://npm.io/package/use-debounce.md) ^9.0.4 ## Alternatives - [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads - [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads - [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads - [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads - [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads ## Recent versions - 0.9.5 (latest) — 2023-08-21 - 0.9.4 — 2023-07-03 - 0.9.3 — 2023-05-05 - 0.9.2 — 2023-05-05 - 0.9.1 — 2023-03-29 - 0.9.0 — 2022-12-22 - 0.8.0 — 2022-12-15 - 0.7.0 — 2022-11-28 - 0.6.1 — 2022-11-27 - 0.6.0 — 2022-11-25 - 0.5.1 — 2022-11-24 - 0.5.0 — 2022-11-24 - 0.4.2 — 2022-11-23 - 0.4.1 — 2022-11-23 - 0.4.0 — 2022-11-23 - … 1 more at https://npm.io/package/react-visual-grid/versions ## README


react-visual-grid logo

[![Status](https://img.shields.io/badge/status-active-success.svg)]() [![License](https://img.shields.io/badge/license-MIT-blue.svg)](/LICENSE) [![codebeat badge](https://codebeat.co/badges/4e12cb98-713b-4835-a118-338f1615ccab)](https://codebeat.co/projects/github-com-prabhuignoto-react-visual-grid-main) [![CodeFactor](https://www.codefactor.io/repository/github/prabhuignoto/react-visual-grid/badge)](https://www.codefactor.io/repository/github/prabhuignoto/react-visual-grid) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-visual-grid) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=prabhuignoto_react-visual-grid&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=prabhuignoto_react-visual-grid) [![Known Vulnerabilities](https://snyk.io/test/github/prabhuignoto/react-visual-grid/badge.svg)](https://snyk.io/test/github/prabhuignoto/react-visual-grid)

⚡ Powerful Image Grid for React

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

- [⚡ Features ](#-features-) - [💭 How it works ](#-how-it-works-) - [⚙️ Installation ](#️-installation-) - [🧋 Usage ](#-usage-) - [🍫 Props ](#-props-) - [🍭 Demo 1 (Horizontal) ](#-demo-1-horizontal-) - [🍭 Demo 2 (Vertical) ](#-demo-2-vertical-) - [ImageProps](#imageprops) - [ImageSizes](#imagesizes) - [Theme](#theme) - [🧱 Masonry](#-masonry) - [🍫 Masonry Props](#-masonry-props) - [⛏️ Built Using ](#️-built-using-) - [✍️ Authors ](#️-authors-) - [🤝Contributing](#contributing) - [Meta](#meta) - [Meta](#meta-1) - [Meta](#meta-2) ## ⚡ Features - 🪟 Generate grids easily. - 🧱 Build beautiful [Masonry](#-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.
![demo](demo.gif)
## 💭 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](#-masonry). The [masonry layout](#-masonry) is used to display images in a grid with varying heights/widths. ## ⚙️ Installation You can install `react-visual-grid` using npm or yarn. ```bash npm install react-visual-grid ``` or ```bash yarn add react-visual-grid ``` ## 🧋 Usage Grids can be generated in two modes: Horizontal and Vertical. The default mode is `vertical` ```js 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 ; }; ``` The dimensions of the grid can be also specified as percentages. ```js import { Grid } from "react-visual-grid"; const App = () => { return ; }; ``` ## 🍫 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](#image-sizes) | | images | Collection of Images to be rendered | [ImageProps](#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](#theme) | | width | Width of the Grid | number or string | 1200 | ## 🍭 Demo 1 (Horizontal) ```js import { Grid } from "react-visual-grid"; const App = () => { return ( ); }; ``` [Horizontal Grid rendering 1k+ images](https://codesandbox.io/s/react-visual-grid-horizontal-e217ix) ## 🍭 Demo 2 (Vertical) ```js import { Grid } from "react-visual-grid"; const App = () => { return ( ); }; ``` [Vertical Grid rendering 1k+ images](https://codesandbox.io/s/react-visual-grid-vertical-bn7yrf?file=/src/App.tsx) ## 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. ```js 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 | ```jsx ``` [Custom Theme](https://codesandbox.io/s/react-visual-grid-vertical-theme-9vc6y3?file=/src/App.tsx) ## 🧱 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. ```jsx 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 ( {dimensions.map(([w, h], index) => ( Image 1 ))} ); }; ``` ![masonry_demo_2](masonry_demo_2.png) [Masonry CodeSandbox](https://codesandbox.io/s/react-visual-grid-masonry-c7x5ws?file=/src/App.tsx) ## 🍫 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](https://www.typescriptlang.org/) - [react](https://reactjs.org/) - [classNames](https://jedwatson.github.io/classnames/) ## ✍️ Authors - [@prabhuignoto](https://github.com/prabhuignoto) - Idea & Initial work ## 🤝Contributing 1. [Fork it](https://github.com/prabhuignoto/react-chrono/fork) 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](https://twitter.com/prabhumurthy2) – prabhu.m.murthy@gmail.com [https://github.com/prabhuignoto](https://github.com/prabhuignoto) --- _Source: https://npm.io/package/react-visual-grid · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._