Fullscreen Lightbox Javascript Fullscreen Lightbox React

React Lightbox Documentation - Pro

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

Download pro version .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-pro-1.0.0.tgz
# or
$ yarn add ./src/lib/fslightbox-react-pro-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!

Thumbs

Thumbs of images are created automatically, if you want to set thumbs of other sources you need to use thumbs prop (array of urls).

<FsLightbox
toggler={ toggler }
sources={[
'images/first.jpg',
'https://www.youtube.com/watch?v=xshEZzpS4CQ',
'videos/video.mp4'
]}
thumbs={[
null,
'images/second.png',
'images/third.jpg'
]}
/>

In above example first source is image so we don't need to set it's thumb (if you want to set different one than image itself - you can, no problem). For the next sources (video and YouTube) we set thumb manually.

Thumbs icons

When displaying videos showing icons on thumbs may improve user experience. To do that you need to use thumbsIcons prop. It's an array of svg's.

<FsLightbox
toggler={ toggler }
sources={[
'https://www.youtube.com/watch?v=xshEZzpS4CQ'
]}
customSources={[
null,
<iframe src="https://player.vimeo.com/video/22439234" frameBorder="0"
allow="autoplay; fullscreen" allowFullScreen/>
]}
thumbs={[
'images/youtube-thumb.jpg',
'images/vimeo-thumb.jpg',
]}
thumbsIcons={[
<svg xmlns="http://www.w3.org/2000/svg" width="28px" height="28px" viewBox="0 0 430.118 430.118">
<path d="M367.243,28.754c-59.795-1.951-100.259,31.591-121.447,100.664c10.912-4.494,21.516-6.762,31.858-6.762 c21.804,0,31.455,12.237,28.879,36.776c-1.278,14.86-10.911,36.482-28.879,64.858c-18.039,28.423-31.513,42.61-40.464,42.61 c-11.621,0-22.199-21.958-31.857-65.82c-3.239-12.918-9.031-45.812-17.324-98.765c-7.775-49.046-28.32-71.962-61.727-68.741 C112.15,34.873,90.98,47.815,62.726,72.308C42.113,91.032,21.228,109.761,0,128.471l20.225,26.112 c19.303-13.562,30.595-20.311,33.731-20.311c14.802,0,28.625,23.219,41.488,69.651c11.53,42.644,23.158,85.23,34.744,127.812 c17.256,46.466,38.529,69.708,63.552,69.708c40.473,0,90.028-38.065,148.469-114.223c56.537-72.909,85.725-130.352,87.694-172.341 C432.498,58.764,411.613,30.028,367.243,28.754z"/>
</svg>,
<svg xmlns="http://www.w3.org/2000/svg" width="30px" height="30px" viewBox="0 0 512 512">
<path d="M490.24,113.92c-13.888-24.704-28.96-29.248-59.648-30.976C399.936,80.864,322.848,80,256.064,80 c-66.912,0-144.032,0.864-174.656,2.912c-30.624,1.76-45.728,6.272-59.744,31.008C7.36,138.592,0,181.088,0,255.904 C0,255.968,0,256,0,256c0,0.064,0,0.096,0,0.096v0.064c0,74.496,7.36,117.312,21.664,141.728 c14.016,24.704,29.088,29.184,59.712,31.264C112.032,430.944,189.152,432,256.064,432c66.784,0,143.872-1.056,174.56-2.816 c30.688-2.08,45.76-6.56,59.648-31.264C504.704,373.504,512,330.688,512,256.192c0,0,0-0.096,0-0.16c0,0,0-0.064,0-0.096 C512,181.088,504.704,138.592,490.24,113.92z M192,352V160l160,96L192,352z"/>
</svg>
]}
/>

In above example we displayed YouTube and Vimeo videos, attached thumbs to it and displayed on those thumbs fitting icons.

Show thumbs on mount

If you want to display thumbs on lightbox mount set showThumbsOnMount prop to true.

<FsLightbox
toggler={ toggler }
sources={ [some sources] }
showThumbsOnMount={ true }
/>

Disable thumbs

If you want to disable thumbs completely set disableThumbs prop to true.

<FsLightbox
toggler={ toggler }
sources={ [some sources] }
disableThumbs={ true }
/>i

Captions

To display captions under slides you need to use array prop - captions. You can fill it with elements you want:

<FsLightbox
toggler={ toggler }
sources={ ['images/first.jpg', 'images/second.jpg', 'images/third.jpg'] }
captions={ [
<>
<h2>First image title</h2>
<div>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</div>
</>,
<h2>Second image title</h2>,
'Third image caption'
] }
/>

Animations

In lightbox there are two animations: initial animation and slide change animation. To edit them you need to use props: initialAnimation and slideChangeAnimation. Just pass class you want to trigger when action occurs:

<FsLightbox
toggler={ toggler }
sources={ [some sources] }
initialAnimation="scale-in-long"
slideChangeAnimation="scale-in"
/>

Toolbar

In pro version there is an option to add your own buttons to toolbar. To do that you need to use customToolbarButtons (array of objects) prop.

<FsLightbox
toggler={ toggler }
sources={ [some sources] }
customToolbarButtons={[
{
viewBox: '0 0 96.124 96.123',
d: 'M72.089,0.02L59.624,0C45.62,0,36.57,9.285,36.57,23.656v10.907H24.037c-1.083,0-1.96,0.878-1.96,1.961v15.803 c0,1.083,0.878,1.96,1.96,1.96h12.533v39.876c0,1.083,0.877,1.96,1.96,1.96h16.352c1.083,0,1.96-0.878,1.96-1.96V54.287h14.654 c1.083,0,1.96-0.877,1.96-1.96l0.006-15.803c0-0.52-0.207-1.018-0.574-1.386c-0.367-0.368-0.867-0.575-1.387-0.575H56.842v-9.246 c0-4.444,1.059-6.7,6.848-6.7l8.397-0.003c1.082,0,1.959-0.878,1.959-1.96V1.98C74.046,0.899,73.17,0.022,72.089,0.02z',
width: '17px',
height: '17px',
title: 'Facebook',
onClick: () => console.log('Facebook button clicked!')
}
]}
/>

Every toolbar button has svg icon inside so required properties are:

  • viewBox: svg icon property
  • d: svg icon property
  • width: width of icon
  • height: height of icon
  • title: caption that will be displayed on button hover
  • onClick: action that will be called after the click

By default custom buttons will be displayed at begin of toolbar. If you want to edit that write some css styles.

/* for example lets reverse order of all buttons */
.fslightbox-toolbar-button:nth-child(1) {
order: 7;
}
.fslightbox-toolbar-button:nth-child(2) {
order: 6;
}
.fslightbox-toolbar-button:nth-child(3) {
order: 5;
}
.fslightbox-toolbar-button:nth-child(4) {
order: 4;
}
.fslightbox-toolbar-button:nth-child(5) {
order: 3;
}
.fslightbox-toolbar-button:nth-child(6) {
order: 2;
}
.fslightbox-toolbar-button:nth-child(7) {
order: 1;
}

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.
onSlideChange Called on slide change.

Just pass a callback function to specific prop.

<FsLightbox
toggler={ toggler }
sources={ [some sources] }
onSlideChange={ (fsLightbox) => {
console.log(fsLightbox);
} }
/>

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 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 }
/>

svg - object prop, with it you can edit icons of every button in lightbox.

<FsLightbox
toggler={ toggler }
sources={ ['source'] }
svg={ {
toolbarButtons: {
thumbs: {
viewBox: '0 0 32 32',
width: '40px',
height: '40px',
d: 'M 6 3 A 1 1 0 0 0 5 4 A 1 1 0 0 0 5 4.0039062',
title: 'Thumbnails'
},
zoomIn: {
width: '40px',
},
zoomOut: {
height: '30px'
},
close: {
height: '32px'
},
fullscreen: {
enter: {
d: 'M121',
},
exit: {
title: 'Fullscreen - exit'
}
},
slideshow: {
start: {
d: 'M123',
},
pause: {
viewBox: '0 0 31 31',
}
}
},
slideButtons: {
previous: {
width: '40px',
},
next: {
title: 'Next'
}
}
} }
/>

There are 5 editable properties for each button: viewBox, width, height, d and title. In above example you can see how to edit some properties in every button.

slideshowTime - number prop. With turned on slideshow - time that need to pass to change slide to next (in milliseconds).

UIFadeOutTime - number prop. Time after UI fades out (in milliseconds).

<FsLightbox
toggler={ toggler }
sources={ ['source'] }
slideshowTime={ 10000 }
/>

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!