Fullscreen Lightbox Javascript Fullscreen Lightbox React

Vanilla Javascript Lightbox Documentation - Pro

Learn how to use Vanilla Javascript Fullscreen Lightbox!

About

Vanilla Javascript Fullscreen Lightbox is library written in pure JavaScript without any additional dependencies. You can display images, videos, whatever you want in full window overlaying box. Have fun!

Browsers

Fullscreen Lightbox was successfully tested on following browsers:

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

Installation

HTML

Download library pro .js file from here and add them to your code.

Just before end of body tag:

<script src="fslightbox.min.js"><script>

How to use

Every <a> tag with data-fslightbox attribute opens a lightbox. Value of href attribute will be shown in your box.

<a data-fslightbox href="https://i.imgur.com/fsyrScY.jpg">
<img src="exampleImage.jpg">
</a>

There is no need to place a specified content inside of <a> tag.

<a data-fslightbox href="/img/example-image.jpg">
John Doe
</a>

Instances

Every unique value of data-fslightbox will be treated as instance. To access specific instance, use it's methods, attach events to it you need to use global fsLightboxInstances object.

<a data-fslightbox="first-lightbox" href="/img/1.jpg">First Lightbox</a>
<a data-fslightbox="second-lightbox" href="/img/2.jpg">Second Lightbox</a>

<script src="fslightbox.min.js"></script>
<script>
fsLightboxInstances['first-lightbox'].open(0);
fsLightboxInstances['second-lightbox'].props.onOpen = () => console.log('Lightbox open!');
</script>

If you have only one instance at page you can access it via global fsLightbox object.

fsLightbox.close();

Refreshing

After adding new <a> tags to detect new lightboxes or update existing ones use global refreshFsLightbox() function.

const a = document.createElement('a');
a.setAttribute('data-fslightbox', 'gallery');
a.setAttribute('href', 'images/2.jpg');
document.body.appendChild(a);

refreshFsLightbox();

Sources

There are 3 types of supported sources: images, videos, YouTube videos. Just pass link to href attribute.

<a data-fslightbox="gallery" href="https://i.imgur.com/fsyrScY.jpg">Image</a>
<a data-fslightbox="gallery" href="https://www.youtube.com/watch?v=xshEZzpS4CQ">YouTube video</a>
<a data-fslightbox="gallery" href="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4">HTML video</a>

Custom sources

To display custom content such as Vimeo videos, Google maps, whatever you want. Lightbox cannot detect default size of such content so to display them you need to use data-width and data-height prop. Instead of passing link to href attribute you need to pass id of custom source with # prefix.

<a data-fslightbox="lightbox" href="#vimeo">Image</a>

<iframe
src="https://player.vimeo.com/video/22439234"
id="vimeo"
frameBorder="0"
allow="autoplay; fullscreen"
allowFullScreen>
</iframe>

There might be a situation in which you don't want to display custom source in website. To achieve that you can use data-custom-class attribute. Class inside of it will be added to source in lightbox:

<a
data-fslightbox="lightbox"
data-custom-class="fslightbox-source"
href="#vimeo">
Image
</a>

<!-- Custom source in website code -->
<iframe
src="https://player.vimeo.com/video/22439234"
id="vimeo"
frameBorder="0"
allow="autoplay; fullscreen"
allowFullScreen>
</iframe>

<!-- Custom source in lightbox -->
<iframe
src="https://player.vimeo.com/video/22439234"
id="vimeo"
class="fslightbox-source"
frameBorder="0"
allow="autoplay; fullscreen"
allowFullScreen>
</iframe>

Types

If you are facing CORS error which blocks automatic content detection you can declare types manually passing it to data-type attribute. Types names are:

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

Thumbs

Thumbs of images are created automatically, if you want to set thumbs of other sources you need to use data-thumb attribute. Just pass url of thumb you want do display:

<a
data-fslightbox="gallery"
data-thumb="/images/example-thumbnail.jpg"
href="https://www.youtube.com/watch?v=xshEZzpS4CQ">
Youtube video
</a>

Or using javascript: thumbs property (array of urls).

fsLightboxInstances['gallery'].props.thumbs = ['/images/example-thumbnail.jpg'];

Thumbs icons

When displaying videos showing icons on thumbs may improve user experience. To do that you need to use thumbsIcons array property.

const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
svg.setAttributeNS(null, 'width', '30px');
svg.setAttributeNS(null, 'height', '30px');
svg.setAttributeNS(null, 'viewBox', '0 0 512 512');

const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
path.setAttributeNS(null, '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.appendChild(path);

fsLightboxInstances['gallery'].props.thumbsIcons = [svg];

Disable thumbs

To disable thumbs completely set disableThumbs property to true.

fsLightboxInstances['gallery'].props.disableThumbs = true;

Display thumbs at start

To show thumbs at lightbox open set showThumbOnMount property to true.

fsLightboxInstances['gallery'].props.showThumbsOnMount = true;

Captions

To display captions at the bottom of slides you can use data-caption property.

<a
data-fslightbox="gallery"
data-caption="<h1>Example title</h1>"
href="/images/1.jpg">
Captioned source
</a>

Or using javascript captions property (array of strings).

fsLightboxInstances['gallery'].props.captions = ['<h2>Example caption</h2>'];

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:

fsLightboxInstances['gallery'].props.initialAnimation = 'initial-animation';
fsLightboxInstances['gallery'].props.slideChangeAnimation = 'slide-change-animation';

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.

fsLightboxInstances['gallery'].props.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.

Set up callback function at specific property on props object, e.g.

fsLightboxInstances['lightbox'].props.onSlideChange = (fsLightbox) => console.log(fsLightbox);

Methods

At every instance there are two methods available:

// opens lightbox at passed index
fsLightboxInstances['lightbox'].open(0);

// closes lightbox
fsLightboxInstances['lightbox'].close();

Others

Disabling local storage

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

fsLightboxInstances['gallery'].props.disableLocalStorage = true;

Videos posters

To display video poster you can use data-video-poster attribute at video <a> tag.

<a
data-fslightbox="lightbox"
data-video-poster="/img/1.jpg"
href="videos/video.mp4">
Video
</a>

Or array prop with images.

fsLightboxInstances['gallery'].props.videosPosters = ['/img/1.jpg'];

Youtube max dimensions

Lightbox cannot detect max sizes of YouTube videos. To manage that you can use data-width and data-height attributes.

<a
data-fslightbox="lightbox"
data-width="1000"
data-height="500"
href="https://www.youtube.com/watch?v=xshEZzpS4CQ">
YouTube
</a>

Or object prop.

fsLightboxInstances['gallery'].props.maxYoutubeDimensions = { width: 1920, height: 1080 };

Slide distance

Distance between slides (x * window.innerWidth), default - 0.3

fsLightboxInstances['gallery'].props.slideDistance = 0.5;

Svg

To edit default svg of toolbar and slide buttons you can overwrite special props:

fsLightboxInstances['gallery'].props.toolbarButtons.thumbs = {
width: '17px',
height: '17px',
viewBox: '0 0 22 22',
d: 'M 3 2 C 2.448 2 2 2.448 2 3 L 2 6 C 2 6.552 2.448 7 3 7 L 6 7 C 6.552 7 7 6.552 7 6 L 7 3 C 7 2.448 6.552 2 6 2 L 3 2 z M 10 2 C 9.448 2 9 2.448 9 3 L 9 6 C 9 6.552 9.448 7 10 7 L 13 7 C 13.552 7 14 6.552 14 6 L 14 3 C 14 2.448 13.552 2 13 2 L 10 2 z M 17 2 C 16.448 2 16 2.448 16 3 L 16 6 C 16 6.552 16.448 7 17 7 L 20 7 C 20.552 7 21 6.552 21 6 L 21 3 C 21 2.448 20.552 2 20 2 L 17 2 z M 3 9 C 2.448 9 2 9.448 2 10 L 2 13 C 2 13.552 2.448 14 3 14 L 6 14 C 6.552 14 7 13.552 7 13 L 7 10 C 7 9.448 6.552 9 6 9 L 3 9 z M 10 9 C 9.448 9 9 9.448 9 10 L 9 13 C 9 13.552 9.448 14 10 14 L 13 14 C 13.552 14 14 13.552 14 13 L 14 10 C 14 9.448 13.552 9 13 9 L 10 9 z M 17 9 C 16.448 9 16 9.448 16 10 L 16 13 C 16 13.552 16.448 14 17 14 L 20 14 C 20.552 14 21 13.552 21 13 L 21 10 C 21 9.448 20.552 9 20 9 L 17 9 z M 3 16 C 2.448 16 2 16.448 2 17 L 2 20 C 2 20.552 2.448 21 3 21 L 6 21 C 6.552 21 7 20.552 7 20 L 7 17 C 7 16.448 6.552 16 6 16 L 3 16 z M 10 16 C 9.448 16 9 16.448 9 17 L 9 20 C 9 20.552 9.448 21 10 21 L 13 21 C 13.552 21 14 20.552 14 20 L 14 17 C 14 16.448 13.552 16 13 16 L 10 16 z M 17 16 C 16.448 16 16 16.448 16 17 L 16 20 C 16 20.552 16.448 21 17 21 L 20 21 C 20.552 21 21 20.552 21 20 L 21 17 C 21 16.448 20.552 16 20 16 L 17 16 z',
title: 'Thumbnails'
};
fsLightboxInstances['gallery'].props.toolbarButtons.zoomIn.width = '20px';
fsLightboxInstances['gallery'].props.toolbarButtons.zoomOut.height = '22px';
fsLightboxInstances['gallery'].props.toolbarButtons.zoomIn.viewBox = '0 0 20 20';
fsLightboxInstances['gallery'].props.toolbarButtons.slideshow.start.width = '25px';
fsLightboxInstances['gallery'].props.toolbarButtons.slideshow.pause.width = '20px';
fsLightboxInstances['gallery'].props.toolbarButtons.fullscreen.enter.title = 'Show';
fsLightboxInstances['gallery'].props.toolbarButtons.fullscreen.exit.title = 'Stop';
fsLightboxInstances['gallery'].props.toolbarButtons.close.viewBox = '0 0 25 25';

fsLightboxInstances['gallery'].props.slideButtons.previous.width = '15px';
fsLightboxInstances['gallery'].props.slideButtons.next.width = '24px';

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.

Slideshow time

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

fsLightboxInstances['gallery'].props.slideshowTime = 10000;

UI fade out time

Time after UI is fades out (in milliseconds).

fsLightboxInstances['gallery'].props.UIFadeOutTime = 10000;

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 detect new <a> tags.

Check out refreshFsLightbox function: link.

Get connected wth us on social networks!