A simple but functional light-box for React

Simple React Light-box (SRL)

Install

Demo

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

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

How to use

Instructions

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:

Note: if you need multiple instance of the light-box in one page you should wrap each one in it's own <SimpleReactLightbox> component.

Next you want to import and use the <SRLWrapper> component wherever you expect the content with the images on which you want to add the light-box functionality. 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.

That's it 🥳 As we are not passing any options you should have a working light-box with the default options like the image below:

The light-box with the default options

Custom gallery

If you want to use the light-box in a more traditional way, like if you want to create a gallery in which thumbnails are wrapped in a link that links to a full width image, now you can. Check the "Gallery with links" example page on the CodeSandbox demo.

Simply wrap your images (ideally the thumbnails) in a link with the data-attribute="SRL". As usual, the alt attribute for the images will be used as caption if declared.

Options

"That's cool and all but the style of the light-box 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 light-box, I have provided all the options that you need to customize the light-box 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. From version 2.8, options are divided in four objects to avoid confusion and to make the code cleaner

The light-box with the custom options

Settings options

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.

hideControlsAfter

number or boolean

3000

Controls how long it will takes for the controls and thumbnails to be hidden. By default all the controls and the thumbnails will be hidden after 3 seconds (3000ms), to create a more immersive experience. This value can't be less then 1000ms. If you want the controls and thumbnails to be always visible set this to FALSE.

disableKeyboardControls

boolean

false

Disable keyboard controls.

disableWheelControls

boolean

false

Disable mouse wheel controls.

disablePanzoom

boolean

false

Disable panzzom controls.

lightboxTransitionSpeed

number

600

Controls the transition speed of when the light-box is opened. This value is in millisecond.

lightboxTransitionTimingFunction

string

"ease"

Controls the transition timing function of when the light-box is opened.

overlayColor

string

"rgba(0, 0, 0, 0.9)"

Controls the background color of the light-box.

slideTransitionSpeed

number

600

Controls the transition speed of each image (when changing from an image to another). This value is in millisecond.

slideTransitionTimingFunction

string

"ease"

Controls the transition timing function of each image (when changing from an image to another).

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.

size

string

"40px"

Controls the size of the buttons

iconPadding

string

"5px"

Increases the padding between the icon and the sides of the button. The more padding you add the smaller the icon will look.

Callbacks

Callbacks can be used in case you need to get information about the state of the light-box 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 light-box so that when you go through the images, your carousel is synced. (Check the example on the demo webiste )

Hooks

There are two hooks that you can use.
The first one is openLightbox. It opens the light-box 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 light-box will just open it from the first image.
The second one is closeLightbox and you can use it to close the light-box.

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 light-box 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.

PanZoom functionality

I added this feature as I think is really cool but is not 100% perfect yet. So in case you have issues with it, just disable it from the options.

Caveats 👮

The images will have an id attribute assigned by Simple React Lightbox. Any other id attribute on the image will be removed. If you are using id attribute in the images, I suggest you use a class attribute instead. I don't think id attribute on images are used a lot but if this is the case let me know and I might adjust the code in the future.