Simple React Light-box (SRL)
A simple but functional light-box for React.
Install
or with Yarn
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.
Declaring images in an array
This approach is approach is definitely supported although is discouraged. Please see the reason why Simple React Lightbox is different by reading the section above to learn more.
Options
I know what you are thinking.
"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 four objects are: settings
, caption
, buttons
, thumbnails
.
The light-box 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. |
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. |
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 |
Caption options
Option | Type | Default value | Description |
---|---|---|---|
showCaption |
boolean |
true |
Show / Hide the caption. |
captionColor |
string |
"#FFFFFF" | Controls the color of the caption. |
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. |
Thumbnails options
Option | Type | Default value | Description |
---|---|---|---|
showThumbnails |
boolean |
true |
Show / Hide the thumbails. |
thumbnailsOpacity |
number |
0.4 | Controls the opacity of the thumbnails. |
thumbnailsSize |
array of strings |
['100px', '80px'] |
Controls the size of the thumbnail. First value in the array is width and the second is height. |
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 )
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 light-box 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 light-box 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 light-box. |
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.
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.