Forem: Michele

How to easily add a lightbox in any React project

Michele — Tue, 15 Dec 2020 22:01:05 +0000

A simple but functional lightbox for React

GitHub | Official Website | CodeSandbox Demo | PRO version demo

A brief introduction 🧐

It all started when I was working on one of my projects with React. The client had a blog site and wanted to add a lightbox to the images in the blog posts. The problem was that the data was fetched from the backend and I had no control over the content of each post.

I looked online for some lightboxes for React, but the way they worked was that I had to declare the images beforehand either in an array, an object, etc… but what if you do not know what content you are getting and you just want to add a lightbox to the images in the content?

Simple React Lightbox gives you the ability to add lightbox functionality to a set of images, whether you define it yourself or get it from an external source (API, backend, etc…). Just use the included component to wrap your app with it, define your options (if you want) and then use the "" component by wrapping it around the content where you have or expect your images!

Packed with features 📦

Since the first version came out, I added tons of new and useful features. Also the PRO version adds even more features. Some of the features are:

Image validation (if you have a broken image, it will be ignored by the lightbox).
Audio e Video support (PRO ONLY)
Exclude elements with a simple custom HTML attribute (PRO ONLY)
Custom icons and custom captions (PRO ONLY)
Support for NextJS and Gatsby and support for Gatsby images.
Observable to check if more images are loaded (for example from an API).
Translations (i18n compatible) to translate the icons using your preferred language (PRO ONLY)
Callbacks to get the status of the lightbox including counting how many images it holds, which slide is selected and which slides comes before and after the current one. *Hooks! One for opening the lightbox (from the first image or passing and index) and one for closing the lightbox.

Install

// With npm
npm install --save simple-react-lightbox
// or with Yarn
yarn add simple-react-lightbox

Usage

I have provided a demo on CodeSandbox for you to play with or you can just follow the instructions below. Alternatively, you can try the full demo with the PRO version on the official website.

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:

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 (Components, Router etc...)
      </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 lightbox functionality. Please note the {} as this is a named export. The caption for the images will be generated from the image "alt" attribute!

`

```
import React from "react";
import { SRLWrapper } from "simple-react-lightbox"; // Import SRLWrapper
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... anything :)
      </SRLWrapper>
  );
}
export default MyComponent;
```

`
That's it 🥳 As we are not passing any options you should have a working lightbox with the default options like the image below:
![The lightbox with default options](https://simple-react-lightbox.dev/docs/SRL_Example1_Git.jpeg)


#### 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 customise the lightbox so that you don't have to add any additional logic. You can customise everything! Check how to add options on the options on the GitHub repo.
The lightbox with custom options
![The lightbox with custom options](https://simple-react-lightbox.dev/docs/SRL_Example2_Git.jpeg)

---

That's it! I hope you enjoy Simple React Lightbox and keep following the project as I am planning to add more features in the future.

Simple-React-Lightbox, a simple but functional light-box for React.

Michele — Thu, 07 May 2020 20:59:31 +0000

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

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…

View on GitHub

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

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…

View on GitHub

Simple React light-box

Michele — Tue, 26 Nov 2019 11:19:32 +0000

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

What's new in Version 3.0

⚠️ HEADS UP! The value for the following options in the settings object have been changed from milliseconds to seconds. slideTransitionSpeed,lightboxTransitionSpeed. If you see a really slow animation is likely because you have forget to change the value. ⚠️
🆕 (added in 3.1) Custom captions are now a thing. I have listened to some feedbacks and now you can make a custom caption with HTML markup and add it to a specific image. Read carefully the documentation on custom captions to see how to use it.
New physics animations for the light-box have been added for realistic motion. The images can now have a "slide" animation where they slide left and right. They…

View on GitHub

A brief introduction 🧐

My Idea 💡

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. Some features are:

PanZoom: allows to zoom on an image and drag it to see all the hidden details!
Autoplay: allows to automatically go to the next image after a set amount of time (which can be configured)
Image validation: excludes broken images so that they will be ignored by the light-box (if you click on a broken images the light-box won't open)
Fully customisable: buttons, caption and background colour can be fully customised
Naturally responsive: Simple React light-box is responsive and supports touch controls. I have also provided clear class names for each part of the light-box in case you need more granular control.

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.

Forem: Michele

How to easily add a lightbox in any React project

A simple but functional lightbox for React

A brief introduction 🧐

Packed with features 📦

Install

Usage

Instructions

Simple-React-Lightbox, a simple but functional light-box for React.

Github

michelecocuccio / simple-react-lightbox

A simple but functional light-box for React.

Simple React Light-box (SRL)

Documentation: quick links

August updates and bugfixes (v3.3)

A brief introduction 🧐

My Idea 💡

Packed with features 📦

Demo

How to use

The light-box with the default options

Custom gallery

Options

There is more to discover

michelecocuccio / simple-react-lightbox

A simple but functional light-box for React.

Simple React Light-box (SRL)

Documentation: quick links

August updates and bugfixes (v3.3)

Simple React light-box

Github

michelecocuccio / simple-react-lightbox

A simple but functional light-box for React.

Simple React Light-box (SRL)

Documentation: quick links

What's new in Version 3.0

A brief introduction 🧐

My Idea 💡

Packed with features 📦

Demo

Images