- A brief introduction
- Demo on CodeSandbox
- Get started
- Options
- Callbacks
- Custom Hook
- Panzoom functionality
- Added a custom hook to open the light-box from anywhere. You can just open the light-box or open it starting from a specific image.
- Added callbacks that can be used when combining the light-box with other libraries. Check the example with Slick Carousel to sync the carousel and the slider.
- The High Order Component has been deprecated in favour of the custom hook. If you were using it and updated the light-box to version 2.5 you might want to use the custom hook instead.
Nothing has changed, you will only see your light-box with the default options. That's because the options have now changed. Don't pass the options to the <SimpleReactLightbox/>
component. Just pass the options to the <SRLWrapper>
It all started when I was working on one of my project using React. The client had a blog page and he wanted to add a light-box to the images in the blog posts. The problem is that the data was fetched from the backend and I had no control over the content of each post (the content was in a WYSIWYG editor).
I checked online for some light-box for React but the way that they were working was that I had to declare the images beforehand in either an array, an object etc...but what if you don't know about the content and you just want to add a light-box to the images? 😞
Simple React Lightbox gives you the ability to add a light-box functionality on a set of images, 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 😮!
From version 1.3 you can create a gallery with links and images as thumbnail. This will give you full control if you want a custom gallery. Check how it works in the "Gallery with links" example page on the CodeSandbox demo
Simple React Lightbox comes with many features: please check the options section to learn more.
npm install --save simple-react-lightbox
or with Yarn
yarn add simple-react-lightbox
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 provided 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.
Simple React Lightbox - Website
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 MyComponent from "./components/MyComponent";
import SimpleReactLightbox from "simple-react-lightbox"; // Import Simple React Lightbox
function App() {
return (
<div className="App">
<SimpleReactLightbox>
<MyComponent /> // Your App logic
</SimpleReactLightbox>
</div>
);
}
export default App;
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!
import { SRLWrapper } from "simple-react-lightbox"; // Import SRLWrapper
function MyComponent() {
return (
<div className="MyComponent">
<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... anything :)
</SRLWrapper>
</div>
);
}
export default MyComponent;
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:
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 points to a full width image, now you can. (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.
import React from "react";
import { SRLWrapper } from "simple-react-lightbox"; // Import SRLWrapper
function MyComponent() {
return (
<div className="MyComponent">
<SRLWrapper>
<a href="link/to/the/full/width/image.jpg" data-attribute="SRL">
<img src="src/for/the/thumbnail/image.jpg" alt="Umbrella" />
</a>
<a href="link/to/the/full/width/image_two.jpg" data-attribute="SRL">
<img src="src/for/the/thumbnail/image_two.jpg" alt="Umbrella" />
</a>
// More images...
</SRLWrapper>
</div>
);
}
export default MyComponent;
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..."
Option | Type | Default | 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. |
buttonIconPadding | string | '0px ' | Increases the padding between the icon and the sides of the button. The more padding you add the smaller the icon will look. |
buttonsBackgroundColor | string | 'rgba(0, 0, 0, 0.9)' | Controls the background color of the buttons. Any CSS Color value is valid. |
buttonsIconColor | 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 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. |
buttonsSize | string | '40px' | Controls the size of the buttons. |
captionFontFamily | string | 'inherit' | Controls the font family of the caption. |
captionFontSize | string | 'inherit' | Controls the font size of the caption. |
captionFontStyle | string | 'inherit' | Controls the font style of the caption. (This is just the CSS property text-transform (none/capitalize/uppercase/lowercase/initial/inherit)) |
captionFontWeight | string | 'inherit' | Controls the font weight of the caption. |
enablePanzoom | boolean | true | Enables or disables the pan-zoom on the image. If you are having issues with the pan-zoom you can disable it from this option. |
hideControlsAfter | number | 3000 | Controls after 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, to create a more immersive experience. If you want the controls and thumbnails to be always visible set this to 0. |
showCaption | boolean | true | Shows/hides the caption. The caption of the images is generated from the image "alt" attribute! |
showThumbnails | boolean | true | Shows/hides the thumbnail gallery. |
slideTransitionSpeed | number | 600 | Controls the transition speed of when an image is swapped with another. Be gentle as using a really high value can potentially cause issues. This value is in millisecond. |
thumbnailsOpacity | number | 0.4 | Controls the opacity of the thumbnails. |
transitionSpeed | number | 600 | Controls the transition speed of when the light-box is opened. This value is in millisecond. |
transitionTimingFunction | string | 'ease' | Controls the transition timing function of when the light-box is opened. It supports all the value of the css transition-timing-function options. |
Passing options is as simple as defining props for a React component. Actually, the options are props for the SRLWrapper component. I will strongly recommend to create a constant with all the options and then pass it to the component with the prop options.
import React from "react";
import MyComponent from "./components/MyComponent";
// Import SRLWrapper
import {SRLWrapper} from "simple-react-lightbox";
// Create an object with the options that we want to use
const options = {
overlayColor: "rgb(25, 136, 124)",
captionColor: "#a6cfa5",
captionFontFamily: "Raleway, sans-serif",
captionFontSize: "22px",
captionFontWeight: "300",
captionFontStyle: "capitalize",
buttonsBackgroundColor: "#1b5245",
buttonsIconColor: "rgba(126, 172, 139, 0.8)",
autoplaySpeed: 1500,
transitionSpeed: 900,
};
function MyComponent() {
return (
<div className="MyComponent">
<SRLWrapper options={options}>
// Your images here
</SRLWrapper>
</div>
);
}
export default MyComponent;
Callbacks can be used in case you need some 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 )
Callback | Args | Return | Usage | Description |
---|---|---|---|---|
onCountSlides | total | integer | (total) => yourFunction(total) | Use this to get the total of the slides. You can pass the total to your function and it will give back an integer with the total count of the slides/images on your light-box. |
onSlideChange | object | object | (object) => yourFunction(object) | Use this every time a slide changes on the light-box. This function will give back an object with the followings: the direction of the slide, the previous, the current and the next slide (as an object) and an index (as an integer) with the index of the current slide. |
onLightboxClosed | none | none | () => yourFunction() | Use this to detect when the light-box is closed |
onLightboxOpened | none | none | () => yourFunction() | Use this to detect when the light-box is opened |
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 React from "react";
import MyComponent from "./components/MyComponent";
// Import SRLWrapper
import {SRLWrapper} from "simple-react-lightbox";
// Create an object with the callbacks that you want to use
const callbacks = {
onCountSlides: total => countSlides(total),
onSlideChange: object => handleSlideChange(object),
onLightboxClosed: () => {},
onLightboxOpened: () => {}
};
function countSlides(total) {
console.log(total);
return total;
}
function handleSlideChange(object) {
console.log(object);
return object;
}
function MyComponent() {
return (
<div className="MyComponent">
<SRLWrapper callbacks={callbacks}>
// Your images here
</SRLWrapper>
</div>
);
}
export default MyComponent;
You can use a custom hook to open the light-box even by selecting a specific image. If you don't provide any argument to the function the light-box will just open it from the first image. 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.
import React from 'react'
import { useLightbox } from 'simple-react-lightbox'
/*
We can use the provided hook in case you want
to open the lightbox from a button or anything :)
*/
const Button = props => {
const openLightbox = useLightbox()
return (
<button
onClick={() => openLightbox(props.imageToOpen)}
>
Open the lightbox
</button>
)
}
export default Button
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.
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.
IE / Edge |
Firefox |
Chrome |
Safari |
iOS Safari |
Samsung |
Opera |
---|---|---|---|---|---|---|
IE11, Edge | last 2 versions | last 2 versions | last 2 versions | last 2 versions | last 2 versions | last 2 versions |
- Use TypeScript