Simple React Lightbox (SRL)

Simple React Lightbox gives you the ability to add a lightbox functionality on a set of images (or videos/audio if you are using the PRO version), whether you define them yourself or you get them from an external source (API, backend etc…). Just use the provided component to wrap your app, define your options and then use the <SRLWrapper> component by wrapping it around the content in which you have or expect your images or videos!

Packed with features 📦

Simple React Lightbox comes with many features: please check the options section to learn more. Some features are only available in the PRO version available on the official Simple React Lightbox - website.

March update (v.3.6.4) / PRO (1.2.3)

Adds a way to help the lightbox to identify the right thumbnail when using Gatsby Image and NextJS Image Component. Please refer to the Gallery with thumbnails section of the docs.
PRO VERSION: New more flexible pricing are going to be available from the 12th of March which allows you to increase the number of downloads per license depending on the plan. Check the official website to learn more.
Added a support for overlay on top of the images in the PRO version that allows to have an overlay DIV on top of an image. You can see this in action on the demo website.

Demo

I have provided a full working demo on CodeSandbox where you can also play with the options and see the lightbox in action.

I have also created a full working website where you can see the lightbox in action. If you want to play with the options, use the CodeSandbox link above.

Simple React Lightbox - Demo website

Getting Started

Install

npm install --save simple-react-lightbox

or with Yarn

yarn add simple-react-lightbox

The installation for the PRO version is slightly different. You will get instructions on how to install the PRO version after the purchase on the Simple React Lightbox - website.

First step (Step 1)

First of all you need to wrap your React app with the main component so that it can create the context. The example below will allow you to use the Simple React Lightbox wherever you need it in your app:

import React from "react";
import ReactDOM from "react-dom";
import App from "./App";
import SimpleReactLightbox from 'simple-react-lightbox'
// USE THE IMPORT BELOW INSTEAD IF YOU ARE USING THE PRO VERSION
// import SimpleReactLightbox from 'simple-react-lightbox-pro'

ReactDOM.render(
  <React.StrictMode>
    <SimpleReactLightbox>
      <App />
    </SimpleReactLightbox>
  </React.StrictMode>,
  document.getElementById("root")
);

export default App;

Note: If you need multiple instances of the lightbox in a single page you should wrap each one with its own component. Although this approach is valid, is not recommended and you should use the composition logic that React offers (for example using multiple components each containing a gallery).

Basic implementation (Step 2)

Next you want to import and use the <SRLWrapper> component wherever you expect the content with the images or videos. Please note the {} as this is a named export. The caption for the images will be generated from the image "alt" attribute so don't forget to add it. The caption for the video and audio elements is manually defined as explained in its own section.

import { SRLWrapper } from "simple-react-lightbox";
// USE THE IMPORT BELOW INSTEAD IF YOU ARE USING THE PRO VERSION
// import { SRLWrapper } from 'simple-react-lightbox-pro'

function MyComponent() {
  return (
    <SRLWrapper>
      // This will be your content with the images.
      // It can be anything. Content defined by yourself,
      // content fetched from an API, data from a graphQL query...
    </SRLWrapper>
  );
}

export default MyComponent;

Done! But there's a lot more...

That's it 🥳 You implemented your lightbox! But you know that there are tons of options that can be implemented? Check the options below.

The lightbox with the default options

Gallery with thumbnails

If you want to create a traditional gallery with some thumbnails that on click trigger the lightbox, you don't have to do anything different apart from making sure you are using a clean syntax like the one showed below.

The anchor tag will point to the full width image while the image will act as thumbnail. The captions is taken from the thumbnail. Simple React Lightbox is smart enough to recognize the link wrapping the image, ignore the thumbnails and trigger the lightbox.

🆕 If the thumbnail is not recognized (for example this happens using NextJS image component), simply add the attribute srl_gallery_image="true" to the image or the component.

import { SRLWrapper } from "simple-react-lightbox";
import Image from 'next/image'

// USE THE IMPORT BELOW INSTEAD IF YOU ARE USING THE PRO VERSION
// import { SRLWrapper } from 'simple-react-lightbox-pro'

function MyComponent() {
  return (
    <SRLWrapper>
      <a href="/link/to/the/full/width/image.jpg">
        <img src="/link/for/the/thumbnail/image.jpg" alt="Umbrella" />
      </a>
      <a href="/link/to/the/full/width/image_two.jpg">
        <img src="/link/for/the/thumbnail/image_two.jpg" alt="Blue sky" />
      </a>
      <a href="/link/for/the/full/width/image/image_three.jpg">
        <Image
          src="/link/for/the/thumbnail/image_three.jpg"
          alt="Picture of the author"
          width={500}
          height={900}
          srl_gallery_image="true" // Add this if your thumbnail is not recognized
        />
      </a>
    </SRLWrapper>
  );
}

export default MyComponent;

Using the lightbox with props

As stated, Simple React Lightbox is different from the competition. But that doesn't mean you can't use it in a more traditional way. In fact you can easily create an array with the elements that you want to pass to the lightbox and pass them using the elements prop. Passing src is the only mandatory requirement for passing a valid element.

import { SRLWrapper } from "simple-react-lightbox";
// USE THE IMPORT BELOW INSTEAD IF YOU ARE USING THE PRO VERSION
// import { SRLWrapper } from 'simple-react-lightbox-pro'

// Create an array of objects that you want to pass to the lightbox
const elements = [
  {
    src: 'https://my/image.jpg',
    caption: 'Lorem ipsum dolor sit amet',
    width: 1920,
    height: 'auto'
  },
  {
    src: 'https://my/second-image.jpg',
    thumbnail: 'https://my/second-image-thumbnails.jpg',
    caption: 'Commodo commodo dolore',
    width: 1024,
    height: 'auto'
  },
  {
    src: 'https://vimeo.com/458698330',
    thumbnail:
      'https://www.simple-react-lightbox.dev/docs/gallery/thumbnails/unsplash05.jpg',
    caption: 'Vimeo video',
    autoplay: false,
    showControls: true
  }
]

function MyComponent() {
  return <SRLWrapper elements={elements} />
}

export default MyComponent;

Options

I know what you are thinking.

"That's cool and all but the style of the lightbox doesn't match the one of my project. That's ok though. I will use your classes and override everything with my custom styles..."

⚠️ WAIT! ⚠️ Despite the fact that I have made sure to define class names for each part of the lightbox, I have provided all the options that you need to customize the lightbox so that you don't have to add any additional logic. You can customize everything!

Passing options is very simple. Just pass the options in a prop called options to the <SRLWrapper> component. I will strongly recommend to create a constant with all the options and then pass it to the component. The options are clearly broken in smaller objects so that you can easily target the option that you need. Some options are only available on the pro version as stated in each section.

const options = {
  settings: {},
  caption: {},
  buttons: {},
  thumbnails: {},
  progressBar:{},
  translations: {}, /* PRO ONLY */
  icons: {} /* PRO ONLY */
}

import React from "react";
import MyComponent from "./components/MyComponent";
// Import SRLWrapper
import {SRLWrapper} from "simple-react-lightbox";

// Create an object with the options that you want to use. The options are divided in 4 main objects. You don't need to define them all.
const options = {
  settings: {
    overlayColor: "rgb(25, 136, 124)",
    autoplaySpeed: 1500,
    transitionSpeed: 900,
  },
  buttons: {
    backgroundColor: "#1b5245",
    iconColor: "rgba(126, 172, 139, 0.8)",
  },
  caption: {
    captionColor: "#a6cfa5",
    captionFontFamily: "Raleway, sans-serif",
    captionFontWeight: "300",
    captionTextTransform: "uppercase",
  }
};

function MyComponent() {
  return (
    <div className="MyComponent">
     // Simply pass the entire object in a prop called "options"
     <SRLWrapper options={options}>
        // Your images here
      </SRLWrapper>
    </div>
  );
}

export default MyComponent;

The lightbox with the custom options

Settings options

Option	Type	Default value	Description
`autoplaySpeed`	`number`	3000	Controls the auto play change interval. Set it to 0 if you don't want to use the auto play functionality and hide the button.
`boxShadow`	`string`	none	Sets a box shadow following the CSS convention.
`disableKeyboardControls`	`boolean`	`false`	Disable keyboard controls.
`disableWheelControls`	`boolean`	`false`	Disable mouse wheel controls.
`disablePanzoom`	`boolean`	`false`	Disable panzzom controls.
`downloadedFileName` 🆕	`boolean`	`SRL-image`	Allows to change the filename of the images when downloaded. Each image will have the filename and the ID of the image in the order they are displayed.
`hideControlsAfter`	`number` or `boolean`	false	Controls how long it will takes for the controls and thumbnails to be hidden. This value can't be less then 1000ms. If you want the controls and thumbnails to be always visible set this to FALSE.
`lightboxTransitionSpeed`	`number`	0.6	Controls the transition speed of when the lightbox is opened. This value is in seconds ⚠️.
`lightboxTransitionTimingFunction`	`string`	"linear"	Controls the transition timing function of when the lightbox is opened. Accepted values are "linear", "easeIn","easeOut", "easeInOut","circIn", "circOut", "circInOut", "backIn", "backOut", "backInOut", "anticipate"
`overlayColor`	`string`	"rgba(0, 0, 0, 0.9)"	Controls the background color of the lightbox.
`slideAnimationType`	`string`	'fade'	Set the type of animation. Possible values are "fade","slide","both". "Fade" is a simple fade in/out animation. "Slide" means that the image will slide left or right (depeding on the direction). This uses the spring physics animation so make sure you set the `slideSpringValues` as settings. "Both" means that the image will slide and fade.
`slideSpringValues`	`array` of `number`	`[300, 200]`	Simulates spring physics for realistic motion. The first value in the array is damping (Strength of opposing force. If set to 0, spring will oscillate indefinitely so don't do it). The second value is stiffness (Stiffness of the spring. Higher values will create more sudden movement).
`slideTransitionSpeed`	`number`	0.6	Controls the transition speed of each image (when changing from an image to another). This value is in seconds ⚠️. This value is going to be ignored if you use the "slide" animation type and the `slideSpringValues` settings will be used instead
`slideTransitionTimingFunction`	`string`	"linear"	Controls the transition timing function of each image (when changing from an image to another). Accepted values are "linear", "easeIn","easeOut", "easeInOut","circIn", "circOut", "circInOut", "backIn", "backOut", "backInOut", "anticipate"
`usingPreact`	`boolean`	false	Set this to TRUE if you are using Preact

const options = {
  settings: {
    autoplaySpeed: 3000,
    boxShadow: 'none',
    disableKeyboardControls: false,
    disablePanzoom: false,
    disableWheelControls: false,
    hideControlsAfter: 3000,
    lightboxTransitionSpeed: 0.3,
    lightboxTransitionTimingFunction: 'linear',
    overlayColor: 'rgba(30, 30, 30, 0.9)',
    slideAnimationType: 'fade',
    slideSpringValues: [300, 50],
    slideTransitionSpeed: 0.6,
    slideTransitionTimingFunction: 'linear',
    usingPreact: false
  }
}

Buttons options

Option	Type	Default value	Description
`backgroundColor`	`string`	"rgba(30,30,36,0.8)"	Controls the background color of the buttons. Any CSS Color value is valid.
`iconColor`	`string`	"rgba(255, 255, 255, 0.8)"	Controls the color of the icons inside the buttons. Any CSS Color value is valid but there is some magic 🎩 happening in here: if you use an rgba() value and set an opacity (like “0.8” as showed in the default value), when you hover with the mouse on the icon this will create a nice CSS hover effect by automatically changing the opacity to “1”, regardless the colour you choose.
`iconPadding`	`string`	"13px"	Increases the padding between the icon and the sides of the button. The more padding you add the smaller the icon will look.
`showAutoplayButton`	`string`	`true`	Show / Hide the autoplay button
`showCloseButton`	`string`	`true`	Show / Hide the close button
`showDownloadButton`	`string`	`true`	Show / Hide the download button
`showFullscreenButton`	`string`	`true`	Show / Hide the fullscreen button
`showNextButton`	`string`	`true`	Show / Hide the next button
`showPrevButton`	`string`	`true`	Show / Hide the previous button
`showThumbnailsButton`	`string`	`true`	Show / Hide the button to hide the thumbnails
`size`	`string`	"40px"	Controls the size of the buttons

const options = {
    buttons: {
      backgroundColor: 'rgba(30,30,36,0.8)',
      iconColor: 'rgba(255, 255, 255, 0.8)',
      iconPadding: '10px',
      showAutoplayButton: true,
      showCloseButton: true,
      showDownloadButton: true,
      showFullscreenButton: true,
      showNextButton: true,
      showPrevButton: true,
      showThumbnailsButton: true,
      size: '40px'
    }
}

Caption options

If you want to use custom captions please read the documentation below.

Option	Type	Default value	Description
`captionAlignment`	`string`	"start"	Align the caption inside its div. Accepted values are "start", "center", "end"
`captionColor`	`string`	"#FFFFFF"	Controls the color of the caption.
`captionContainerPadding`	`string`	"20px 0 30px 0"	Adds padding to the div containing the caption. You can use the CSS shortened syntax like "10px 5px" which will add 10px of padding top and bottom and 5px left and right.
`captionFontFamily`	`string`	"inherit"	Controls the font family of the caption. By default it will inherit the one from the parent element.
`captionFontSize`	`string`	"inherit"	Controls the font size of the caption. By default it will inherit the one from the parent element.
`captionFontStyle`	`string`	"inherit"	Controls the font style of the caption. By default it will inherit the one from the parent element.
`captionFontWeight`	`string`	"inherit"	Controls the font weight of the caption. By default it will inherit the one from the parent element.
`captionTextTransform`	`string`	"inherit"	Controls the "text-transform" property of the caption. By default it will inherit the one from the parent element.
`showCaption`	`boolean`	`true`	Show / Hide the caption.

const options = {
  // Please note that "caption" is singular
  caption: {
    captionAlignment: 'start',
    captionColor: '#FFFFFF',
    captionContainerPadding: '0',
    captionFontFamily: 'inherit',
    captionFontSize: 'inherit',
    captionFontStyle: 'inherit',
    captionFontWeight: 'inherit',
    captionTextTransform: 'inherit',
    showCaption: true
  }
}

Thumbnails options

Option	Type	Default value	Description
`showThumbnails`	`boolean`	`true`	Show / Hide the thumbails.
`thumbnailsAlignment`	`string`	"center"	Align the thumbnails in their div. Accepted values are "start", "center", "end", "space-between", "space-around"
`thumbnailsContainerBackgroundColor`	`string`	"transparent"	Adds a background color to the div containing the thumbnails.
`thumbnailsContainerPadding`	`string`	"0"	Adds padding to the div containing the thumbnails. You can use the CSS shortened syntax like "10px 5px" which will add 10px of padding top and bottom and 5px left and right.
`thumbnailsGap`	`string`	"0 1px"	Gap between the thumbnails;
`thumbnailsIconColor`	`string`	"#ffffff"	In the case of a video element, you will see a "play" icon in the thumbnails. You can control the color of the icon here.
`thumbnailsOpacity`	`number`	0.4	Controls the opacity of the thumbnails.
`thumbnailsPosition`	`string`	'bottom'	Controls where the thumbnails are going to be displayed. If displayed left and right, thumbnails will be stacked vertically.
`thumbnailsSize`	`array` of `strings`	`['100px', '80px']`	Controls the size of the thumbnail. First value in the array is width and the second is height.

const options = {
  thumbnails: {
    showThumbnails: true,
    thumbnailsAlignment: 'center',
    thumbnailsContainerBackgroundColor: 'transparent',
    thumbnailsContainerPadding: '0',
    thumbnailsGap: '0 1px',
    thumbnailsIconColor: '#ffffff',
    thumbnailsOpacity: 0.4,
    thumbnailsPosition: 'bottom',
    thumbnailsSize: ['100px', '80px']
  }
}

Progress bar options

Option	Type	Default value	Description
`backgroundColor`	`string`	"#f2f2f2"	The background color of the progress bar.
`fillColor`	`string`	"#000000"	The fill color of the progress bar.
`height`	`string`	"3px"	The height of the progress bar.
`showProgressBar`	`boolean`	`true`	Show / Hide the progress bar.

const options = {
  progressBar: {
    backgroundColor: '#f2f2f2',
    fillColor: '#000000',
    height: '3px',
    showProgressBar: true
  }
}

Translations options (PRO only)

Option	Type	Default value	Description
`autoplayText`	`string`	"Play"	The text for the play button when the lightbox is not playing
`closeText`	`string`	"Close"	The text for the close button
`downloadText`	`string`	"Download"	The text for the download button
`fullscreenText`	`string`	"Full Screen"	The text for the full screen button
`nextText`	`string`	"Next"	The text for the next slide button
`previousText`	`string`	"Previous"	The text for the previous slide button
`pauseText`	`string`	"Pause"	The text for the play button when the lightbox is playing
`thumbnailsText`	`string`	"Hide thumbnails"	The text for the hide thumbnails button
`zoomOutText`	`string`	"Zoom out"	The text for the zoom out button when the pan zoom is activate

const options = {
  translations: {
    autoplayText: 'Play',
    closeText: 'Close',
    downloadText: 'Download',
    fullscreenText: 'Full screen',
    nextText: 'Next',
    pauseText: 'Pause',
    previousText: 'Previous',
    thumbnailsText: 'Hide thumbnails',
    zoomOutText: 'Zoom Out'
  }
}

Custom icons (PRO only)

If you are using the PRO version of Simple React Lightbox, you will have access to another object in the options, called icons in which you can pass your custom icons as an image. Ideally you would pass a transparent PNG image but it's entirely up to you.

Option	Type	Default value	Description
`autoplayIcon`	`string`	null	The autoplay icon.
`closeIcon`	`string`	null	The close icon.
`downloadIcon`	`string`	null	The download icon.
`fullscreenIcon`	`string`	null	The fullscreen icon.
`nextIcon`	`string`	null	The next icon.
`previousIcon`	`string`	null	The previous icon.
`thumbnailsIcon`	`string`	null	The thumbnails icon.
`zoomOutIcon`	`string`	null	The zoomOut icon.

const options = {
  icons: {
    autoplayIcon: null,
    closeIcon: null,
    downloadIcon: null,
    fullscreenIcon: null,
    nextIcon: null,
    pauseIcon: null,
    previousIcon: null,
    thumbnailsIcon: null,
    zoomOutIcon: null
  }
}

Video and audio support

PRO only

If you are using the PRO version, Simple React Lightbox will add support to audio links (from SoundCloud) and videos (YouTube, Twitch, Vimeo, DailyMotion and web videos). There are some custom HTML attributes you can pass to control the video/audio element.

If you get an error from the player, you probably passed a wrong URL. YouTube videos for example, must be passed without the "channel" argument for now (this will be fixed soon.) A valid YouTube URL will look like this: https://www.youtube.com/watch?v=aS1no1myeTM

Attribute	Type	Default value	Description
`srl_video_caption`	`string`	null	TDefine the caption for the video/audio.
`srl_video_thumbnail`	`string`	null	Define the thumbnail for the video/audio.
`srl_video_width`	`string`	"100%"	Define the width of the video if you need a custom size. Otherwise the video will adapt itself to the ratio which by default is 16/9.
`srl_video_height`	`string`	"100%"	Define the heigth of the video if you need a custom size. Otherwise the video will adapt itself to the ratio which by default is 16/9.
`srl_video_ratio`	`string`	"16/9"	By default videos will have a ratio of `16/9`. Another option available is `4/3` in the case of some old videos.
`srl_video_scale`	`string`	"60"	If you want to keep the video with the correct ratio and just scaled it up or down you can use this value (from `0` to `100`) to scale the video accordingly.
`srl_video_controls`	`string`	true	Show / Hide video/audio control where supported.
`srl_video_autoplay`	`string`	true	Set autoplay for the video/audio where supported.
`srl_video_muted`	`string`	false	Set muted for the video/audio where supported.
`srl_video_loop`	`string`	true	Set loop for the video/audio where supported.

Web video (Mp4, Webm, Ogv)

In the case of web videos you can pass them as per usual using the HTML video element. In this case you will pass the custom HTML attributes to the video element.

import { SRLWrapper } from "simple-react-lightbox";
// USE THE IMPORT BELOW INSTEAD IF YOU ARE USING THE PRO VERSION
// import { SRLWrapper } from 'simple-react-lightbox-pro'

function MyComponent() {
  return (
    <div className="MyComponent">
      <SRLWrapper>
        <video
          width="100%"
          height="100%"
          srl_video_thumbnail="./videos/video_thumbnail_01.jpg"
          srl_video_caption="A video with a rabbit"
          srl_video_muted="true"
        >
          <source src="./videos/bunny.mp4" type="video/mp4" />
          <source src="./videos/bunny.webm" type="video/webm" />
          <source src="./videos/bunny.ogv" type="video/ogg" />
          Your browser does not support the video tag.
        </video>
      </SRLWrapper>
    </div>
  );
}

export default MyComponent;

If you don't want to display the video element and want to display a custom image, just put an image before it and hide the video using CSS.

<SRLWrapper>
  <div>
    <img src="https://url/to/video_thumbnail.jpg" />
    <video
      srl_video_thumbnail="https://url/to/video_thumbnail.jpg"
      srl_video_caption="An epic video"
      srl_video_controls="true"
      srl_video_autoplay="true"
      srl_video_muted="true"
      style={{ display: 'none' }}
    >
      <source src="./videos/bunny.mp4" type="video/mp4" />
      <source src="./videos/bunny.webm" type="video/webm" />
      <source src="./videos/bunny.ogv" type="video/ogg" />
      Your browser does not support the video tag.
    </video>
  </div>
</SRLWrapper>

Embed Video/Audio (YouTube, Twitch, Vimeo, Dailymotion, SoundCloud)

In the case of an embed video, just wrap an image with a link to the embed video in which you will pass the custom HTML attributes.

<SRLWrapper>
  <a
    srl_video_thumbnail="https://url/to/my_twitch_thumbnail.jpg"
    srl_video_loop="true"
    srl_video_scale="80"
    srl_video_caption="Twitch video"
    href="https://www.twitch.tv/videos/778219281"
  >
    <img src="https://url/to/my_twitch_thumbnail.jpg" />
  </a>

  <a
    srl_video_thumbnail="https://url/to/my_audio_thumbnail.jpg"
    srl_video_caption="Audio Track"
    href="https://soundcloud.com/miami-nights-1984/accelerated"
  >
    <img src="https://url/to/my_audio_thumbnail.jpg" />
  </a>
</SRLWrapper>

Custom Captions

PRO only

If you want one or more image to have a fully customized caption, you can now do it by declaring an array of objects and passing it to the a prop on the <SRLWrapper> called customCaptions. Each object in the array has two values:

id which is the image you want to add the custom caption to. Remember that the id is starting from 0 so id: 0 will target the first image, id: 4 the fifth and so on...
caption this will contain your custom caption. You can use JSX/HTML markup and so you can have buttons, links and anything you like.

Check the example on the demo website

⚠️ NOTES:

If you are using a button, or a link or anything you want clickable or selectable, you need to add a class of SRLCustomCaption to every element, including children. This is to prevent the lightbox from closing when clicking outside which is the normal behavior of the lightbox.
All the settings about the caption are being ignored if you are using a custom caption. You dictate the style of your custom caption. Keep in mind that the caption was designed to be just that, a caption, and I am not responsible if your layout breaks for any reason (like if you put too many things in it).

  import { SRLWrapper } from "simple-react-lightbox";
  // USE THE IMPORT BELOW INSTEAD IF YOU ARE USING THE PRO VERSION
  // import { SRLWrapper } from 'simple-react-lightbox-pro'

  // JSX can be assigned to a variable
  const captionOne = (
    <div className="SRLCustomCaption myCustomCaptionOne">
      She found herself in a <span className="SRLCustomCaption">forest...</span>
    </div>
  )
  const captionTwo = (
    <div className="SRLCustomCaption myCustomCaptionTwo">
      ...lost and wandering she had to
      <span className="SRLCustomCaption">make a choice...</span>
    </div>
  )
  const captionThree = (
    <a
      href="http://www.simple-react-lightbox.dev"
      target="__blank"
      className="SRLCustomCaption myCustomButton"
    >
      Help her make a choice
    </a>
  )

  // Create an array with the custom captions that you want to use
  const customCaptions = [
    { id: 0, caption: captionOne },
    { id: 1, caption: captionTwo },
    { id: 2, caption: captionThree }
  ]

  function MyComponent() {
    return (
      <div className="MyComponent">
      <SRLWrapper customCaptions={customCaptions}>
          {/* Your elements here (image or video/audio). Images 0,1,2 will use a custom caption.  */}
        </SRLWrapper>
      </div>
    );
  }

Usage with overlay DIV

(PRO Only)

If you are using the PRO version version you can use overlay on the images. This is particularly useful when using a gallery of images in an e-commerce website. In order to achieve this a special div must be included before the image and it must include a custom attribute called srl_overlay="true".

The code structure must follow the exact order (DIV with the overlay first, image after) as shown in the code example (the overlay structure is entirely up to you of course). Overlay CSS is up to you of course and the overlay must be on top of the image in order to be clickable.

import { SRLWrapper } from "simple-react-lightbox";
// USE THE IMPORT BELOW INSTEAD IF YOU ARE USING THE PRO VERSION
// import { SRLWrapper } from 'simple-react-lightbox-pro'

function MyComponent() {
  return (
    <SRLWrapper>

    // First image
    <a href="/product01.jpg" className="element_with_overlay">
    // Overlay DIV with the custom attribute
      <div className="overlay" srl_overlay="true">
        <h1>Funny cap</h1>
        <p>£30.00</p>
      </div>
      <img src="product/01.jpg" alt="Funny cap"/>
    </a>

    // Second image
    <a href="/product02.jpg" className="element_with_overlay">
    // Overlay DIV with the custom attribute
      <div className="overlay" srl_overlay="true">
        <h1>Sunglasses</h1>
        <p>£90.00</p>
      </div>
      <img src="product/02.jpg" alt="Sunglasses"/>
    </a>

    // Third Image (Not using a thumbnail)
    <div className="element_with_overlay">
      <div className="overlay" srl_overlay="true">
        <h1>Funny cap</h1>
        <p>£30.00</p>
      </div>
      <img
        src="/product03.jpg"
        alt="Cool backpack"
      />
    </div>

    </SRLWrapper>
  )
}

export default MyComponent;

Hooks

There are two hooks that you can use. The first one is openLightbox. It opens the lightbox and you can pass an argument which is the index of the slide you want to open (starting from 0).If you don't provide any argument to the function the lightbox will just open it from the first image. The second one is closeLightbox and you can use it to close the lightbox.

Check the demo to see it in action. In the example below we are creating a reusable React component (a button) that can open the lightbox from anywhere in your app. Please note that from version 2.8 you need to destructure the useLightbox() hook to get the function that you need.

import { useLightbox } from 'simple-react-lightbox'
// USE THE IMPORT BELOW INSTEAD IF YOU ARE USING THE PRO VERSION
// import { useLightbox } from 'simple-react-lightbox-pro'

export default function Buttons() {
  const { openLightbox, closeLightbox } = useLightbox()

  return (
    <>
      <button onClick={() => openLightbox(2)}>
        Open the third image
      </button>
      <button onClick={() => openLightbox()}>
        Open the lightbox
      </button>
      <button onClick={() => closeLightbox()}>
        Close the lightbox
      </button>
    </>
  )
}

Callbacks

Callbacks can be used in case you need to get information about the state of the lightbox or to access the different slides (images). A good example of this could be if you, for example, wanted to sync a carousel with the lightbox so that when you go through the images, your carousel is synced. (Check the example on the demo website )

Callback	Args	Returns	Usage	Description
`onSlideChange`	`object`	`{index: integer`, `action: string}`, `slides: {previous: {}, current: {}, next: {}}`	`(object) => { console.log('object) }`	Use this to detected when a slide changes. Gives back the current slide index, the action take (left, right or selected) and an object with the previous, current and next slide.
`onLightboxOpened`	`object`	`{currentSlide: {...}}, opened: true`	`(object) => { console.log('object) }`	Use this to detected when the lightbox is opened. It returns an object with the current slide and another one with a key of "opened" and a value of "true".
`onLightboxClosed`	`object`	`{currentSlide: {...}}, opened: false`	`(object) => { console.log('object) }`	Use this to detected when the lightbox is closed. It returns an object with the current slide and another one with a key of "opened" value of "false".
`onCountSlides`	`total`	`{totalSlide: integer}`	`(total) => { console.log('total) }`	Use this to get the total of the slides. You can pass the total as an argument to your callback function and it will give back an integer with the total count of the slides/images on your lightbox.

Yes, callbacks! But how do I use them?

Callbacks are passed with the callbacks prop to the SRLWrapper. I will strongly recommend to create a constant with all of your callbacks and then pass it to the component with the prop callbacks.

import { SRLWrapper } from "simple-react-lightbox";
// USE THE IMPORT BELOW INSTEAD IF YOU ARE USING THE PRO VERSION
// import { SRLWrapper } from 'simple-react-lightbox-pro'

// Create an object with the callbacks that you want to use
const callbacks = {
    onSlideChange: object => console.log(object),
    onLightboxOpened: object => console.log(object),
    onLightboxClosed: object => console.log(object),
    onCountSlides: object => console.log(object)
};

function MyComponent() {
  return (
    <div className="MyComponent">
     <SRLWrapper callbacks={callbacks}>
        // Your images here
      </SRLWrapper>
    </div>
  );
}

export default MyComponent;

Firefox issue

I have noticed that sometimes Firefox has issues on rendering the "slide" animation. I will need to investigate this fully but I think it's related to a bug with Firefox and semi-transparent background. The solution is to change the overlayColor option to have a color without any transparency. If you really want the transparency you can do a little hack and change the variable if the browser is Firefox. This only occurs rarely and especially with the "slide" animation. The "fade" animation should work perfectly regardless.

import { SRLWrapper } from "simple-react-lightbox";
// USE THE IMPORT BELOW INSTEAD IF YOU ARE USING THE PRO VERSION
// import { SRLWrapper } from 'simple-react-lightbox-pro'

const browser = navigator.userAgent
const isFirefox = browser.indexOf('Firefox') > -1

const options = {
    settings: {
      overlayColor: isFirefox ? '#000000' : 'rgba(0,0,0,0,8)'
    }
};

function MyComponent() {
  return (
    <div className="MyComponent">
     <SRLWrapper options={options}>
        // Your images here
      </SRLWrapper>
    </div>
  );
}

export default MyComponent;

Browsers support

Edge	Firefox	Chrome	Safari	iOS Safari	Samsung	Opera
Edge	last 2 versions	last 2 versions	last 2 versions	last 2 versions	last 2 versions	last 2 versions

What the future holds 🔮

Use TypeScript

Name		Name	Last commit message	Last commit date
Latest commit History 451 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
src		src
.editorconfig		.editorconfig
.eslintrc		.eslintrc
.gitignore		.gitignore
.prettierrc		.prettierrc
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
yarn.lock		yarn.lock

License

goguda/simple-react-lightbox

Folders and files

Latest commit

History

Repository files navigation

Simple React Lightbox (SRL)

Packed with features 📦

Documentation: quick links

March update (v.3.6.4) / PRO (1.2.3)

Demo

Getting Started

Install

First step (Step 1)

Basic implementation (Step 2)

Done! But there's a lot more...

The lightbox with the default options

Gallery with thumbnails

Using the lightbox with props

Options

The lightbox with the custom options

Settings options

Buttons options

Caption options

Thumbnails options

Progress bar options

Translations options (PRO only)

Custom icons (PRO only)

Video and audio support

PRO only

Web video (Mp4, Webm, Ogv)

Embed Video/Audio (YouTube, Twitch, Vimeo, Dailymotion, SoundCloud)

Custom Captions

PRO only

Usage with overlay DIV

(PRO Only)

Hooks

Callbacks

Yes, callbacks! But how do I use them?

Firefox issue

Browsers support

What the future holds 🔮

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages