react-responsive-gallery

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

Main features

• Support both types of media: image and video.
• Custom for every screen width size.
• Dynamic properties for every screen width size.
• Media could be selected and controlled/uncontrolled easily.
• Accessibility support.
• Simple to use.
• Work with Lightbox for media display.
• Full typescript support.
• Tested with React Testing Library.
  

Getting started

 npm install react-responsive-gallery

or

 yarn add react-responsive-gallery

Playground

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

Basic using example

import ReactDOM from 'react-dom/client';
import ResponsiveGallery from 'react-responsive-gallery';

const media=[
{
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'
}
];

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<ResponsiveGallery media={media}/>);

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
media	Array	Array of media elements 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
numOfMediaPerRow	Object	Number of media elements for row by the width groups.	{xs: 1,s: 2,m: 3,l: 3,xl: 4 xxl:5}	Optinal
mediaMaxWidth	Object	Media max width in % by the width groups.	{xs: 100,s: 100,m: 100,l: 100,xl: 100,xxl:100}	Optional
colsPadding	Object	Padding between media cols in px by the width groups.	{xs: 4,s: 4,m: 4,l: 4,xl: 4,xxl:4}	Optional
mediaMarginBottom	Object	Margin bottom between media in px by the width groups.	{xs: 4,s: 4,m: 4,l: 4,xl: 4,xxl:4}	Optional
mediaClassName	string	Class name that will apply on all the media on gallery	None	Optional
mediaStyle	Object	Object Style that will apply on all the media on gallery	None	Optional
useLightBox	Boolean	Use lightbox when clicking on media	false	Optional
lightBoxAdditionalProps	object	Additional props for the lightbox component. Read more here	false	Optional
selectable	boolean	Media could be selectable. Read more here	false	Optional
selectableMedia	Array	Chosen media as part of the selectable items.	None	Optional
onSelect	Function - (id:string,val:boolean)=>void	Callback function when media is selected.	None	Optional
onClick	Function - (id:string)=>void	Callback function when media is clicked.	None	Optional
customLoader	React component	Loader show when media is loading		Optional
customError	React component	Error show when media failed to load		Optional

Media Options

Property	Type	Description	Required	Relevant to
src	String	Media source url	Required	Image / Video
type	String("image"/"video")	Image/Video source url	Optional, default is "image"	Image / Video
id	String	Media Id (Read more here)	Optional (only if src is unique)	Image,Video
alt	String	Image alternate text	Optional	Image
orderS	Number	Media order in small group sizes(xs, s)	Optional	Image,Video
orderM	Number	Media order in medium group sizes (m,l)	Optional	Image,Video
orderL	Number	Media order in large group sizes(xl,xxl)	Optional	Image,Video
mediaClassName	String	Media className for styling specific media element	Optional	Image / Video
mediaStyle	Object	Media object style for styling specific media element	Optional	Image / Video
title	String	Lightbox media title	Optional	Image
videoType	"video/mp4" / "video/webm" / "video/ogg"	Type of the video element	Optional, default is "video/mp4"	Video
additionalVideoProps	Object	Additional attributes for video as describe here	Optional	Video

:warning: if you set orderS/orderL/orderM property only to part of the media elements the library first sorts the media elements with the property and then renders the other media elements.

If you will not pass the media id

We need some unique identifier for every media eleemnt. Usually we use the `src` attribute but it's will be valid only if the `src` is unique. The media `id` is required if the media src is not unique.
If `src` property is not unique and media `id` is not supply the library will not work as expected.

Selectable Media

Media could be selected via the gallery.

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

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

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

Using Lightbox

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

:warning: These properties are not available to send as additional props (because we already using them internally): open, close, slides

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.