React Grid Gallery

Justified image gallery component for React inspired by Google Photos and based upon React Images.

📣 Maintainers wanted 📣

As react-grid-gallery continues to gain popularity and provide value to many users (around half a million downloads from NPM as of August 2020) it requires maintainers to at least take care of issues and pull requsts. If you're getting value from using this component or if you're just interested in becoming a maintainer, please let me know.

Note:

As of the release of v0.5.4 (2019-03-10) I will no longer be actively adding features and maintaining react-grid-gallery. My online behavioral experiment platform Psychstudio consumes all of my time and I am no longer capable of giving react-grid-gallery the attention it needs. A big thanks to everyone who has contributed over the last 5 years and thanks to everyone who has downloaded react-grid-gallery (hopefully it has been useful to you).

Live Demo & Examples

https://benhowell.github.io/react-grid-gallery/

• Main Demo
• Pre-selected Images
• Permanently Selected Images
• Simple Gallery
• Custom Overlay
• Thumbnail Captions
• Custom Lightbox Controls

Installation

Using npm:

npm install --save react-grid-gallery

Quick (and dirty) Start

import React from 'react';
import { render } from 'react-dom';
import Gallery from 'react-grid-gallery';

const IMAGES =
[{
        src: "https://c2.staticflickr.com/9/8817/28973449265_07e3aa5d2e_b.jpg",
        thumbnail: "https://c2.staticflickr.com/9/8817/28973449265_07e3aa5d2e_n.jpg",
        thumbnailWidth: 320,
        thumbnailHeight: 174,
        isSelected: true,
        caption: "After Rain (Jeshu John - designerspics.com)"
},
{
        src: "https://c2.staticflickr.com/9/8356/28897120681_3b2c0f43e0_b.jpg",
        thumbnail: "https://c2.staticflickr.com/9/8356/28897120681_3b2c0f43e0_n.jpg",
        thumbnailWidth: 320,
        thumbnailHeight: 212,
        tags: [{value: "Ocean", title: "Ocean"}, {value: "People", title: "People"}],
        caption: "Boats (Jeshu John - designerspics.com)"
},

{
        src: "https://c4.staticflickr.com/9/8887/28897124891_98c4fdd82b_b.jpg",
        thumbnail: "https://c4.staticflickr.com/9/8887/28897124891_98c4fdd82b_n.jpg",
        thumbnailWidth: 320,
        thumbnailHeight: 212
}]

render(
        <Gallery images={IMAGES}/>,
        document.getElementById('example-0')
);

Image Options

Gallery Options

Lightbox Options

NOTE: these options are passed inside the Gallery tag.

e.g.

<Gallery images={IMAGES} backdropClosesModal={true}/>

General Notes

• react-grid-gallery is built for modern browsers and therefore IE support is limited to IE 11 and newer.

• As the inspiration for this component comes from Google Photos, very small thumbnails may not be the most aesthetically pleasing due to the border size applied when selected. A sensible rowHeight default of 180px has been chosen, but rowHeights down to 100px are still reasonable.

• Gallery width is determined by the containing element. Therefore your containing element must have a width (%, em, px, whatever) before the gallery is loaded!

• Image Options: thumbnail can point to the same resource as src, bearing in mind the resultant data size of the gallery and page load cost. Thumbnails of whatever size will be scaled to match rowHeight.

Programmers Notes

• User defined functions that allow access to this via Function.prototype.call() do not require you to declare or pass this as a parameter. this will be defined at the time the function is called.

e.g.

// somewhere in your code...
function myTileViewportStyleFn() {
  if (this.props.item.isSelected)
    return {
           // something stylish...
            };
}

<Gallery images={IMAGES} tileViewportStyle={myTileViewportStyleFn}/>


// internally, within the react-grid-gallery component it will be called like so:
myTileViewportStyleFn.call(this); // this now refers to the image to be styled

• If you don't know your thumbnailWidth and thumbnailHeight values, you can find these out using any number of javascript hacks, bearing in mind the load penalty associated with these methods.

Contributing

All contributions to react-grid-gallery are very welcome. Feature requests, issue reports and pull requests are greatly appreciated. Please follow the contribution guidelines

License

React Grid Gallery is free to use for personal and commercial projects under the MIT License. Attribution is not required, but appreciated.

Acknowledgements

• Visual design inspired by Google Photos.

• Thumbnail viewport implementation inspired by GPlusGallery by Florian Maul.

• Backend lightbox functionality via React Images by jossmac.

• The following gallery functions were obtained from the React Images example demo: closeLightbox, gotoNext, gotoPrevious, handleClickImage, openLightbox.

• cust0dian for critical bug fixes in PR 6 and PR 7.

• ValYouW for lightboxWillOpen and lightBoxWillClose functionality PR 20 and customOverlay option: PR 22.

• danalloway for theme pass-through prop PR 27

• SimeonC for update thumbnails when maxRows changes PR 35 and resize on scrollbar presence change PR 40

• jakub-tucek for thumbnailCaption functionality PR 42

• mis94 for EXIF image rotation functionality PR 67

• forforf for contentWindow check PR 77

• ScottMRafferty for preloadNextImage not propagating to Lightbox fix PR 78

• Approximator for currentImageWillChange (Function to execute before lightbox image change) PR 97.

• Vadimuz for nano image props and functionality PR 101.

• pxpeterxu for adding functionality to inject a custom thumbnail image component (for lazy-loading) PR 104.

• lryta for fixing crash when this.props.images.length - 1 < this.state.currentImage PR #111.

• jimishf for lightBoxProps option to assign any prop directly to lightbox PR #121.

• Demo stock photos:

  • Jeshu John - designerspics.com
  • Gratisography
  • Tom Eversley - isorepublic.com
  • Jan Vasek - jeshoots.com
  • moveast.me
  • 贝莉儿 NG. - unsplash.com
  • Matthew Wiebe. - unsplash.com