README.md

React Responsive Photo Gallery

A stateless responsive React photo gallery component that maintains the original aspect ratio of your photos and scales them responsively. Add your own routing, lightbox, and manage your own state.

Installation

To install:

npm install --save react-photo-gallery

Demo

http://neptunian.github.io/react-photo-gallery/

To build the examples locally, run:

npm install
npm start

Then open localhost:8000 in a browser.

Use

import React from 'react';
import Gallery from 'react-photo-gallery';

export default class Sample extends React.Component {
    render() {
	return (
	    <Gallery photos={PHOTO_SET} onClickPhoto={this.openLightbox}/>
	);
    }
}
const PHOTO_SET = [
  {
    src: 'http://example.com/example/img1.jpg',
    srcset: [
      'http://example.com/example/img1_1024.jpg 1024w',
      'http://example.com/example/img1_800.jpg 800w',
      'http://example.com/example/img1_500.jpg 500w',
      'http://example.com/example/img1_320.jpg 320w',
    ],
    sizes:[
      '(min-width: 480px) 50vw',
      '(min-width: 1024px) 33.3vw',
      '100vw'
    ],
    width: 681,
    height: 1024,
    alt: 'image 1',
  },
  {
    src: 'http://example.com/example/img2.jpg',
    srcset: [
      'http://example.com/example/img2_1024.jpg 1024w',
      'http://example.com/example/img2_800.jpg 800w',
      'http://example.com/example/img2_500.jpg 500w',
      'http://example.com/example/img2_320.jpg 320w',
    ],
    sizes:[
      '(min-width: 480px) 50vw',
      '(min-width: 1024px) 33.3vw',
      '100vw'
    ],
    width: 600,
    height: 600,
    alt: 'image 2',
  }
];

Gallery properties

Property	Type	Default	Description
photos	array	undefined	required; array of objects
cols	number	3	optional; number of photos per row
onClickPhoto	function	function	optional; do something when the user clicks a photo
margin	number	2	optional; number of margin pixels around each entire image

Gallery.photos properties

Property	Type	Default	Description
src	string	undefined	required; the img src attribute value of the gallery image
srcset	string	undefined	optional; the img srcset attribute value of the gallery image
sizes	string	undefined	optional; the img sizes attribute value of the gallery image
width	number	undefined	required; original width of the gallery image (only used for calculating aspect ratio)
height	number	undefined	required; original height of the gallery image (only used for calculating aspect ratio)
alt	string	undefined	optional; alt text of the gallery image

Demo explanation

This component uses React Images for lightbox functionality in the example demo, but the component itself does not depend on it. PHOTO_SET obj in the example above is also being passed to lightbox which uses src, srcset, and caption props.

To gain a good understanding of 'srcset' and 'sizes' attributes, I found this site very helpful: https://ericportis.com/posts/2014/srcset-sizes/.

User Guide / Best Practice

Dynamic column count

The parameter cols allows the adjustment of the displayed colums. In combination with react-measure this allows the demo page to adjust colums (https://github.com/neptunian/react-photo-gallery/blob/master/examples/src/app.js#L103). Code snippet:

import { Measure } from 'react-measure';
function ResponseiveGallery (props) {
  const { maxImageWidth = 300 } = props;
  return (
    <Measure whitelist={['width']}>
      {({ width }) => (
        <Gallery cols={Math.ceil(width / maxImageWidth)}>....</Gallery>
      )}
    </Measure>
  );
}

This idea was discussed in #32 and proposed by @smeijer.