Fullscreen Lightbox Javascript Fullscreen Lightbox React Fullscreen Lightbox Vue

Vue Lightbox Documentation - Basic

Learn how to use Vue Fullscreen Lightbox!

About

Vue Fullscreen Lightbox is powerful Vue component. In these docs you can read how to use all features off Fullscreen Lightbox.

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

Package manager

You can install lightbox using your favorite package manager:

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

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

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

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

Passing props to custom sources

To do it instead of passing component directly pass object with component and props properties:

<FsLightbox
:toggler="toggler"
:customSources="[{
component: CustomSource
props: { exampleProp: 'example-value' }
}]"
/>

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>

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

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

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

export default {
components: { FsLightbox },
data() {
return {
toggler: false,
}
},
methods: {
action() {
console.log('lightbox initialized');
}
}
};
</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"
/>

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!