TypeScript icon, indicating that this package has built-in type declarations

4.0.0 • Public • Published

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

example workflow

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


 yarn add react-responsive-gallery


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: ''
src: ''
src: ''
src: ''
src: ''
src: ''
src: ''
src: ''
src: ''
src: ''

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.

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 loader Optional
customError React component Error show when media failed to load error 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

⚠️ 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.

⚠️ 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.
⚠️ 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'.

⚠️ 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.

Package Sidebar


npm i react-responsive-gallery

Weekly Downloads






Unpacked Size

142 kB

Total Files


Last publish


  • oriamir