README.md

Simple-React-Lightbox (SRL)

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 😮!

🆕 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

Packed with features 📦

Simple React Lightbox comes with many features: please check the options section to learn more.

---

Install

npm install --save simple-react-lightbox

or with Yarn

yarn add simple-react-lightbox

How to use

Demo

I have provided a working demo on Codesandbox

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
      </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 React from "react";
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:

The light-box with the default options

🆕 Custom gallery

Due to popular demand I have now added the option to use the light-box in a more traditional way. 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;

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! Check the options below.

Option	Type	Default	Description
overlayColor	string	rgba(0, 0, 0, 0.9)	Sets the background color of he light-box. You can set an rgba() value if you want to control the opacity. Any CSS Color value is valid.
captionStyle	object	captionStyle: { captionColor: "#FFFFFF", captionFontFamily: "inherit", captionFontSize: "inherit", captionFontWeight: "inherit", captionFontStyle: "inherit" },	This is an object that defines the styles for the caption. You can control the color, size, font-family, weight and style of the font. Those values depends, of course, on the font that you are using. captionFontStyle is just the CSS property text-transform (none/capitalize/uppercase/lowercase/initial/inherit).
buttonsStyle	object	buttonsStyle: { buttonsBackgroundColor: "rgb(30,30,36,0.8)", buttonsIconColor: "rgba(255, 255, 255, 0.8)"},	This is an object that defines the style for the buttons and the icon inside the button. So you can control both of them easily. Any CSS Color value is valid but there is some magic 🎩 happening in here: if you use an rgba() value for the icon 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.
autoplaySpeed	number	3000	Controls the auto play change interval. Set it to 0 if you don't want to use the auto play functionallity and you want to hide the button.
transitionSpeed	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.
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.

Yes, options! But how do I use them?

Passing options is as simple as defining props for a React component. Actually, the options are props for the SimpleReactLightbox component. I will strongely reccomend to create a constant with all the options and then spread it in the component. Is fast, readable and easy to change. Thanks ES6 😎

import React from "react";
import MyComponent from "./components/MyComponent";
// Import Simple React Lightbox
import SimpleReactLightbox from "simple-react-lightbox";

// Create an object with the options that we want to use
const options = {
  overlayColor: "rgb(25, 136, 124)",
  captionStyle: {
    captionColor: "#a6cfa5",
    captionFontFamily: "Raleway, sans-serif",
    captionFontSize: "22px",
    captionFontWeight: "300",
    captionFontStyle: "capitalize"
  },
  buttonsStyle: {
    buttonsBackgroundColor: "#1b5245",
    buttonsIconColor: "rgba(126, 172, 139, 0.8)"
  },
  autoplaySpeed: 1500,
  transitionSpeed: 900,
};

function App() {
  return (
    <div className="App">
      /* Using the spread operator, we spread the options.
      You could also define the options one by one like
     <SimpleReactLightbox overlayColor={"rgba(255,255,255,0.9)"} captionStyle={{captionColor: "red"}}
     But...why?
     */
     <SimpleReactLightbox {...options}>
        <MyComponent /> // Your App logic
      </SimpleReactLightbox>
    </div>
  );
}

export default App;

The light-box with the custom options

High Order Component

⚠️ Please note this feature might be removed in the future ⚠️ Sometimes you may have a lot of images and yes, the user could open the light-box by clicking on the first one. But every website is designed differently and UI / UX play a big part when designing and coding a website. So I created a HOC High Order Component that you can use to get access to two methods:

Method	Description
openLightbox	Opens the light-box starting from the first image.
closeLightbox	Closes the light-box.

and this is how you use the High Order Component

import React from "react";
// Import the High Order Component
import { withSRLContext } from "simple-react-lightbox";

const MyComponent = props => {
  // We have access to the methods inside the props
  <div>
    <button onClick={props.openLightbox}>Open lightbox</button>
    <a onClick={props.closeLightbox}>Close lightbox</a>
  </div>
}

// Wrap your component with the High Order Component
export withSRLContext(MyComponent);

To be honest I don't really see a reason to use that, especially the "closeLightbox" method so I might consider to remove this in the near future.

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.

Browsers support

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

What the future holds 🔮

• Custom options for each light-box
• Use TypeScript