React-Responsive-Gallery - Responsive Gallery for react application.

Main features

• Custom for every screen width size.
• Dynamic properties for every screen width size.
• Images could be selected and controlled/uncontrolled easily.
• Simple to use.
• Work with Lightbox for image display.
• Full typescript support.
• Tested with React Testing Library.
  

Getting started

 npm install react-responsive-gallery

or

 yarn add react-responsive-gallery

DEMO

Try out the live gallery demo . (it's take few seconds until app is loading)
* Some of the gallery features are not available in the live demo : cols padding , imagesStyle and images order(s,m,l).

Playground

You can play with the library in Codesandbox or in Stackblitz .

Basic using example

import React from 'react';
import { render } from 'react-dom';
import ResponsiveGallery from 'react-responsive-gallery';

const images=[
{
src: 'https://cdn.pixabay.com/photo/2017/01/14/12/59/iceland-1979445_960_720.jpg'
},
{
src: 'https://cdn.pixabay.com/photo/2019/06/12/15/07/cat-4269479_960_720.jpg'
},
{
src: 'https://cdn.pixabay.com/photo/2016/12/04/21/58/rabbit-1882699_960_720.jpg'
},
{
src: 'https://cdn.pixabay.com/photo/2014/07/08/12/36/bird-386725_960_720.jpg'
},
{
src: 'https://cdn.pixabay.com/photo/2015/10/12/15/46/fallow-deer-984573_960_720.jpg'
},
{
src: 'https://cdn.pixabay.com/photo/2014/10/01/10/44/hedgehog-468228_960_720.jpg'
},
{
src: 'https://cdn.pixabay.com/photo/2013/09/22/15/29/prairie-dog-184974_960_720.jpg'
},
{
src: 'https://cdn.pixabay.com/photo/2018/03/31/06/31/dog-3277416_960_720.jpg'
},
{
src: 'https://cdn.pixabay.com/photo/2016/12/13/05/15/puppy-1903313_960_720.jpg'
},
{
src: 'https://cdn.pixabay.com/photo/2019/03/09/17/30/horse-4044547_960_720.jpg'
}
];

render(
<ResponsiveGallery images={images}/>,
document.getElementById('root')
);

Width groups explanation

The Gallery has 6 different of width groups: xs, s, m, l, xl, xxl .
The Gallery renders again when the group changes.
You can change the group sizes by your preferences , the default group values are:

• xs: From 0 to 420px
  
  
• s: From 420px to 600px
  
  
• m: From 600px to 768px
  
  
• l: From 768px to 992px
  
  
• xl: From 992px to 1200px
  
  
• xxl: From 1200px to infinity
  
  

*You don't need to specify 'xxl' in your 'screenWidthSizes' object because it's take your max 'xl' group value until infinity.

Gallery options

Property	Type	Description	Default value	is Required
images	Array	Array of images to display in the gallery. Read more here	None	Required
screenWidthSizes	Object	Gallery groups width break points.	{xs: 420,s: 600,m: 768,l: 992,xl: 1200}	Optional
numOfImagesPerRow	Object	Number of images for row by the width groups.	{xs: 1,s: 2,m: 3,l: 3,xl: 4 xxl:5}	Optinal
imageMaxWidth	Object	Image max width in % by the width groups.	{xs: 100,s: 100,m: 100,l: 100,xl: 100,xxl:100}	Optional
colsPadding	Object	Padding between images cols in px by the width groups.	{xs: 4,s: 4,m: 4,l: 4,xl: 4,xxl:4}	Optional
imagesPaddingBottom	Object	Padding bottom between images in px by the width groups.	{xs: 4,s: 4,m: 4,l: 4,xl: 4,xxl:4}	Optional
imagesStyle	Object / String	Style that will apply on all the images on gallery	None	Optional
useLightBox	Boolean	Use lightbox when clicking on image	false	Optional
lightBoxAdditionalProps	object	Additional props for the lightbox component. Read more here	false	Optional
selectable	boolean	Images could be selectable. Read more here	false	Optional
selectableItems	Array	Chosen images as part of the selectable items.	None	Optional
onSelect	Function - (id:string,val:boolean)=>void	Callback function when image is selected.	None	Optional

Images Options

Property	Type	Description	is Required
src	String	Image source url	Required
id	String	Image Id (Read more here)	Optional
alt	String	Image alternate text	Optional
orderS	Number	Image order in small group sizes(xs, s)	Optional
orderM	Number	Image order in medium group sizes (m,l)	Optional
orderL	Number	Image order in large group sizes(xl,xxl)	Optional
imgClassName	Object / String	Image style object/string for styling specific image	Optional
lightboxCaption	String	Lightbox image caption	Optional
lightboxTitle	String	Lightbox image title	Optional

⚠️ if you set orderS/orderL/orderM property only to part of the images the library first sorts the images with the property and then renders the other images.

Selectable Images

Images could be selected via the gallery.

The library expose function and hook to manage the images:
getSelectedImages- function that return id's array of the selected images.
useSelect- hook that return id's array of the selected images , then we could listen to changes in the images if needed.
This hook will work as expected only AFTER the dom is initialized with the images.

You can control the selected images yourself in your component or just get the images using function/hook.
Uncontrolled - The library will manage the selected images and you will get them using the getSelectedImages function. To use that functionally you just need to pass the selectable boolean attribute to the library.
Controlled - You will manage the selected images yourself using selectableItems and onSelect functions.

⚠️ If you will not pass the image id property to the image element the selected image will return as URL representation instead of id representation. In the case of a duplicate image URL, this feature will not work as expected.
⚠️ When passing the onSelect function to the library it's automatically move to Uncontrolled mode and will not manage the selected images any more.

Using Lightbox

You can use lightbox when clicking on one of the images that display on the gallery. For the lightbox component library we use the react-image-lightbox library.
You can sent the props from this library and to send them as prop to library called 'lightBoxAdditionalProps'.

⚠️ These properties are not available to send as additional props (because we already using them internally): mainSrc, nextSrc, prevSrc, onCloseRequest, onMovePrevRequest, onMoveNextRequest
⚠️ If you want to pass imageTitle or imageCaption you can pass that via the img props.

Author

Ori Amir

Bugs and Feedback

For bugs, questions and discussions please use the Github Issues.

License

React Responsive Gallery is free to use for personal and commercial projects under the MIT License.