Fullscreen Lightbox Javascript Fullscreen Lightbox React Fullscreen Lightbox Vue

Vue Lightbox Documentation - Pro

Learn how to use full version Vue Fullscreen Lightbox!

About

Vue Fullscreen Lightbox Pro is full version of powerful Vue component. In these docs you can read how use all it's features.

Browsers

Fullscreen Lightbox was successfully tested on following browsers:

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

Dependencies

Name Version
vue at least 2.5.0

Installation

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

<template>
<div>
<button @click="toggler = !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'
]"
/>
</div>
</template>

<script>
import FsLightbox from "fslightbox-vue";
export default {
components: { FsLightbox },
data() {
return {
toggler: false
}
}
}
</script>

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 Vue key prop. When this prop updates Vue remounts component.

<template>
<div>
<button @click="toggler = !toggler">
Toggle Lightbox
</button>

<button @click="productIndex = 1">
Load second product
</button>

<FsLightbox
:toggler="toggler"
:sources="productsImages[productIndex]"
:key="productIndex"
/>
</div>
</template>

<script>
import FsLightbox from "fslightbox-vue";

export default {
components: { FsLightbox },
props: {
productsImages: Array
},
data() {
return {
toggler: false,
productIndex: 0,
}
}
}
</script>

Custom sources

With customSources prop you can display content such as Vimeo videos, Google maps, whatever you want. Custom source needs to be Vue component (How to pass props to components?):

<template>
<div>
<button @click="toggler = !toggler">
Toggle Lightbox
</button>

<FsLightbox
:toggler="toggler"
:customSources="[CustomSource]"
/>
</div>
</template>

<script>
import FsLightbox from "fslightbox-vue";
import CustomSource from "./CustomSource.vue"

export default {
components: { FsLightbox },
data() {
return {
toggler: false,
CustomSource: CustomSource
}
}
}
</script>

Example custom source (Vimeo video):

<template>
<iframe src="https://player.vimeo.com/video/22439234" width="1920px" height="1080px"
frameBorder="0" allow="autoplay; fullscreen" allowFullScreen />
</template>

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.

<template>
<div>
<button @click="openLightboxOnSlide(1)">
Open lightbox on first slide
</button>

<button @click="openLightboxOnSlide(2)">
Open lightbox on second slide
</button>

<FsLightbox
:toggler="toggler"
:slide="slide"
:sources="['img/1.jpg', 'img/2.bmp']"
/>
</div>
</template>

<script>
import FsLightbox from "fslightbox-vue";

export default {
components: { FsLightbox },
data() {
return {
toggler: false,
slide: 1
}
},
methods: {
openLightboxOnSlide: function(number) {
this.slide = number;
this.toggler = !this.toggler;
}
}
}
</script>

Thumbs icons

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 or overwrite default ones 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 components (How to pass props to components?).

<FsLightbox
:toggler="toggler"
:sources="[
'https://www.youtube.com/watch?v=xshEZzpS4CQ',
'videos/video.mp4'
]"
:thumbs="[
'image/youtube-thumb.jpg',
'image/video-thumb.jpg'
]"
:thumbsIcons="[
YoutubeIcon,
VideoIcon
]"
/>

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="['https://i.imgur.com/fsyrScY.jpg']"
:showThumbsOnMount="true"
/>

Disable thumbs

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

<FsLightbox
:toggler="toggler"
:sources="['https://i.imgur.com/fsyrScY.jpg']"
:disableThumbs="true"
/>

Captions

To display captions under slides you need to use array prop - captions. Fill it with captions components (How to pass props to components?).

<FsLightbox
:toggler="toggler"
:sources="['images/first.jpg', 'images/second.jpg']"
:captions="[
ExampleCaption,
{
component: DifferentCaption,
props: {
exampleProp: 'example-value'
}
}
]"
/>

Animations

In lightbox there are two animations:

  • initialAnimation - triggered on each source load
  • slideChangeAnimation - triggered on slide change

Just pass class you want to trigger. Remember - each animation must contain different class.

<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.

<template>
<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: customButtonOnClick
}
]"
/>
</template>

<script>
import FsLightbox from "fslightbox-vue";
export default {
components: { FsLightbox },
data() {
return {
toggler: false
}
},
methods: {
customButtonOnClick() {
console.log('Custom button clicked');
}
}
}
</script>

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. Example:

<template>
<FsLightbox
:toggler="toggler"
:sources="[some sources]"
:onSlideChange="action"
/>
</template>

<script>
import FsLightbox from "fslightbox-vue";

export default {
components: { FsLightbox },
data() {
return {
toggler: false,
}
},
methods: {
action(instance) {
console.log(instance);
}
}
};
</script>

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

toolbarButtons - object prop, with it you can edit icon of every default button in toolbar.

<FsLightbox
:toggler="toggler"
:sources="['source']"
: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',
}
}
}"
/>

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 of every icon.

slideButtons - object prop, with it you can edit icon of previous and next slide button.

<FsLightbox
:toggler="toggler"
:sources="['source']"
:slideButtons="{
previous: {
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: 'Left'
},
next: {
width: '40px'
}
}"
/>

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).

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

How to pass props to components passed to FsLightbox props?

Instead of passing component directly push object with component and props properties. Example:

<template>
<FsLightbox
:toggler="toggler"
:custom-sources="[{
component: Vimeo,
props: {
exampleProp: 'example-value'
}
}]"
/>
</template>

<script>
import FsLightbox from "fslightbox-vue";
import VimeoComponent from "./Vimeo.vue";

export default {
components: { FsLightbox },
data() {
return {
toggler: false,
Vimeo: VimeoComponent,
}
}
};
</script>

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!