Github
Check the project on Github to read the full documentation
michelecocuccio
/
simple-react-lightbox
A simple but functional light-box for React.
Simple React Light-box (SRL)
Documentation: quick links
- A brief introduction
- Demo on CodeSandbox
- Get started
- Options
-
Custom Captions
🆕 - Callbacks
- Custom Hook
- A note on "slide" animation and Firefox
August updates and bugfixes (v3.3)
-
Translations has been added to the list of options. Now you can change the title of the buttons with the text that you want and you can translate it to your preferred language.
-
Full screen mode has been improved. Now you can use the interface of Simple React Lightbox while being on full screen.
-
Fixed a bug that was causing the image to shake when panning and zooming on IOS.
-
Fixed a bug that was causing the thumbnails to wrongly position themself on IOS.
-
Fixed a bug that was causing the light-box to be unable to recognize the source of the image when using Gatsby image with the "Gallery with thumbnails" mode.
-
Fixed a…
A brief introduction 🧐
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? 😞
My Idea 💡
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 😮! It takes less than 1 minute to implement it.
Each light-box is individually configurable both in terms of styles and options. That means that you can easily adapt the style of the light-box to your project.
Packed with features 📦
Simple React Lightbox comes with many features: please check the options section to see the full list of options. Since the first version came out, I added tons of new and useful features. The most recent one includes:
- Image validation (if you have a broken image, it will be ignored by the light-box).https://dev.to/new
- Support for NextJS and Gatsby and support for Gatsby images.
- Observable to check if more images are loaded (for example from an API).
- Callbacks to help you in case the user needs to get the status of the light-box including counting how many images it holds, which slide is selected and which slides comes before and after the current one.
- New and redesigned options, to make your code cleaner and more readable and to make the light-box easier to use.
- Hooks! One for opening the light-box (from the first image or passing and index) and one for closing the light-box.
- Many more…
Demo
I have provided a working demo on CodeSandbox where you can also play with the options and see the light-box in action. This is the same as running the demo locally. Alternatively, you can play with a demo on the official website of Simple-React-Lightbox
How to use
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 Simple React Lightbox
import SimpleReactLightbox from "simple-react-lightbox";
function App() {
return (
<div className="App">
// Wrap your app with the component
<SimpleReactLightbox>
<MyComponent /> // Your App logic
</SimpleReactLightbox>
</div>
);
}
export default 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.
// Import SRLWrapper
import { SRLWrapper } from "simple-react-lightbox";
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:
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.
import React from "react";
// Import SRLWrapper
import { SRLWrapper } from "simple-react-lightbox";
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="Whatever" />
</a>
</SRLWrapper>
</div>
);
}
export default MyComponent;
Options
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.
const options = {
settings: {},
caption: {},
buttons: {},
thumbnails: {}
}
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;
There is more to discover
Please check the project on Github to read the full documentation and to get a full list of the options available.
michelecocuccio
/
simple-react-lightbox
A simple but functional light-box for React.
Simple React Light-box (SRL)
Documentation: quick links
- A brief introduction
- Demo on CodeSandbox
- Get started
- Options
-
Custom Captions
🆕 - Callbacks
- Custom Hook
- A note on "slide" animation and Firefox
August updates and bugfixes (v3.3)
-
Translations has been added to the list of options. Now you can change the title of the buttons with the text that you want and you can translate it to your preferred language.
-
Full screen mode has been improved. Now you can use the interface of Simple React Lightbox while being on full screen.
-
Fixed a bug that was causing the image to shake when panning and zooming on IOS.
-
Fixed a bug that was causing the thumbnails to wrongly position themself on IOS.
-
Fixed a bug that was causing the light-box to be unable to recognize the source of the image when using Gatsby image with the "Gallery with thumbnails" mode.
-
Fixed a…
Top comments (1)
Really cool. Does it work with videos?