Fullscreen Lightbox Javascript Fullscreen Lightbox React

React Lightbox Documentation - Basic

Learn how to use React Fullscreen Lightbox!

About

React Fullscreen Lightbox is powerful React component. You can display whatever you want with clean overlaying box.

Browsers

Fullscreen Lightbox was successfully tested on following browsers:

  • Google Chrome
  • Mozilla Firefox
  • Microsoft Edge
  • Internet Explorer 11
  • Opera

Dependencies

Name Version
react at least 16.8.0
react-dom at least 16.8.0

Installation

Package manager

You can install lightbox using your favorite package manager:

$ npm install --save-dev fslightbox-react
# or
$ yarn add --dev fslightbox-react

Tarball

Download .tgz archive from download page . Put it somewhere in your project for example: ./src/lib Then run package manager install command with path to that archive. You need to be in directory where your project package.json file is.

$ npm install ./src/lib/[lightbox archive name]
# or
$ yarn add ./src/lib/[lightbox archive name]

Example:

$ npm install ./src/lib/fslightbox-react-basic-1.0.0.tgz
# or
$ yarn add ./src/lib/fslightbox-react-basic-1.0.0.tgz

How to use

Lightbox will be created from urls given in sources props. You don't need to specify content type, lightbox will do it for you. To work component requires at least two props:

toggler - on every update of this prop lightbox will close or open (depending on current state).
Lightbox is closed and toggler is being updated - lightbox opens.
Lightbox is opened and toggler is being updated - lightbox closes.

sources - array with urls, which will be displayed in lightbox.

import React, { useState } from 'react';
import FsLightbox from 'fslightbox-react';

function App() {
// if toggler is updated when lightbox is closed it will open it
// if toggler is updated when lightbox is opened it will close it
const [toggler, setToggler] = useState(false);

return (
<>
<button onClick={ () => setToggler(!toggler) }>
Toggle Lightbox
</button>
<FsLightbox
toggler={ toggler }
sources={ [
'images/random-image.jpg',
'https://i.imgur.com/fsyrScY.jpg',
'https://www.youtube.com/watch?v=xshEZzpS4CQ',
'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4'
] }
/>
</>
);
}

export default App;

Sources

To display images, HTML videos, YouTube videos you need to use sources array prop. You can give full url or only path.

Important!

Sources prop is not reactive. If you want to display new sources you need to remount lightbox. In most cases best solution is to use React key prop. When this prop updates React remounts component.

function App({ productsImages }) {
const [toggler, setToggler] = useState(false);
const [productIndex, setProductIndex] = useState(0);

return (
<>
<button onClick={ () => setToggler(!toggler) }>
Toggle Lightbox
</button>
<button onClick={ () => setProductIndex(1) }>
Load second product
</button>
<FsLightbox
toggler={ toggler }
sources={ productsImages[productIndex] }
key={ productIndex }
/>
</>
);
}

Custom sources

With customSources prop you can display content such as Vimeo videos, Google maps, whatever you want:

function App({ productsImages }) {
const [toggler, setToggler] = useState(false);
const [productIndex, setProductIndex] = useState(0);

return (
<>
<button onClick={ () => setToggler(!toggler) }>
Toggle Lightbox
</button>
<FsLightbox
toggler={ toggler }
customSources={[
<iframe src="https://player.vimeo.com/video/22439234" width="1920px" height="1080px"
frameBorder="0" allow="autoplay; fullscreen" allowFullScreen />,
<iframe src="//maps.google.com/maps?q=?&q=London&output=embed" width="1920px" height="1080px"
allowFullScreen="allowfullscreen" scrolling="no" allow="autoplay; fullscreen" />,
<div style={ { width: '200px', height: '100px'} }>
<h3>I'm a completely custom source</h3>
</div>
]}
/>
</>
);
}

Important!

Functional components cannot be custom sources - you need to wrap them with some element.

Types

If you are facing CORS error which blocks automatic content detection you can declare types manually passing strings to special props. Types names are:

  • image type - 'image'
  • video type - 'video'
  • YouTube type - 'youtube'

Props

types - array with strings which declares types of specific sources
type - string which declares type for all sources

<FsLightbox
toggler={ toggler }
sources={ ['first-source', 'second-source', 'third-source'] }
type="image"
types={ [null, null, 'video'] }
/>

In above example we've set image type globally, but overwritten it with video for the third source. So finally types are: image, image, video

Control slide number

If you are making gallery it's often useful to open lightbox on specific slide not the first one. There comes three props:

slide: - you can pass here slide number directly: 1 (first slide), 2 (second slide) etc.
sourceIndex: - you can pass here source index that you want to display: 0 (first slide), 1 (second slide) etc.
source - you can pass here full source name that you want to display: 'images/1.jpg' (first slide), 'videos/2.mp4' (second slide) etc.

function App() {
const [lightboxController, setLightboxController] = useState({
toggler: false,
slide: 1
});

function openLightboxOnSlide(number) {
setLightboxController({
toggler: !lightboxController.toggler,
slide: number
});
}

return (
<>
<button onClick={ () => openLightboxOnSlide(1) }>
Open lightbox on first slide.
</button>
<button onClick={ () => openLightboxOnSlide(2) }>
Open lightbox on second slide.
</button>
<FsLightbox
toggler={ toggler }
sources={ [
'image/1.jpg',
'image/2.bmp'
] }
slide={ lightboxController.slide }
/>
</>
);
}

In above example we used slide prop. Others (sourceIndex, source) are used similarly. Choose one that suits you best!

Events

There are few events that you can listen for:

Prop When fired?
onOpen Every time instance is opened (both show and initialize).
onClose Every time instance is closed.
onInit When instance is opened for the first time.
onShow When opening instance after initial open.

Just pass a callback function to specific prop.

<FsLightbox
toggler={ toggler }
sources={ [some sources] }
onInit={ () => {
console.log('initialized');
} }
/>

Other props

disableLocalStorage - to improve performance lightbox caches detected types in local storage, if you dont't want that you set this boolean prop to true. It's useful when you are taking sources with different types from same url e.g.

<FsLightbox
toggler={ toggler }
sources={ ['https//videosandimages.s3.com'] }
disableLocalStorage={ true }
/>

videosPosters - array with strings, declare videos posters e.g.

<FsLightbox
toggler={ toggler }
sources={ ['images/1.jpg', 'videos/video.mp4'] }
videosPosters={ [null, 'images/2.jpg'] }
/>

maxYoutubeVideoDimensions - object with width and height number property, declares max dimensions of YouTube videos, if not set default dimensions are: width - 1920(px), height - 1080(px)

<FsLightbox
toggler={ toggler }
sources={ ['https://www.youtube.com/watch?v=xshEZzpS4CQ'] }
maxYoutubeVideoDimensions={ { width: 1920, height: 1080 } }
/>

openOnMount - boolean, if set to true lightbox will open on mount

slideDistance - number, distance between slides (x * window.innerWidth), default - 0.3

<FsLightbox
toggler={ toggler }
sources={ ['source'] }
slideDistance={ 0.5 }
/>

UI

You are able to edit user interface by overriding default Fullscreen Lightbox styles. Easiest way to find classes you want to edit is to explore lightbox DOM in devtools.
To show an example let's assume you want to edit toolbar:

/* let's change order of buttons (toolbar has display: flex) */
.fslightbox-toolbar-button:nth-child(1) {
order: 2;
}

/* or hide fullscreen button at low resolution */
.fslightbox-toolbar-button:nth-child(1) {
display: none;
}

@media(min-width:576px) {
.fslightbox-toolbar-button:nth-child(1) {
display: flex;
}
}

FAQ

I've passed correct url but lightbox displays message: Invalid file!

You've most likely used external url without CORS enabled so lightbox cannot detect it's type automatically.

There are two ways to fix it:

  • you can put source you want to display on your server
  • you can specify source type manually using types prop. More...

Lightbox doesn't change sources!

sources and customSources props are not reactive, how to change lightbox sources?

Get connected wth us on social networks!