SilentBox logo

Silentbox 3

A simple lightbox inspired Vue.js component.

A third version of the lightweight lightbox inspired component for Vue.js with local video support and more features coming. Completely rewritten in TypeScript for Vue3.

Supported formats and services

Installation and usage

Terminal

npm install --save vue-silentbox
                
app.js

import { createApp } from 'vue'
import VueSilentbox from 'vue-silentbox'
import 'vue-silentbox/dist/style.css'

createApp({
    data: {
        images: [
            {
                src: 'images/image001.jpg',
                srcSet: '/images/image001-640.jpg 640w,/images/image001-1280.jpg 1280w,/images/image001-1920.jpg 1920w',
                description: 'Sunken dreams II. by Arbebuk',
            }
            // rest of your images ...
        ]
    },
})
.use(VueSilentbox)
.mount('#root')
                
index.html

<silent-box :gallery="gallery"></silent-box>
                

Plugin options

You can set the following options to the plugin to change the behaviour of the SilentBox or display additional information.

option required type default description
downloadButtonLabel no string Download Label of the download button when enabled.

Image attributes

These attributes can be set to the image in the gallery.

attribute type description
src string media source, it could be an image or a youtube video
srcSet string srcSet to make use of responsive images
thumbnail string link to the image that will be used as a thumbnail
thumbnailHeight string height of the thumbnail in px
thumbnailWidth string width of the thumbnail in px
description string short description below image (doesn't work below videos yet)
alt string alt description for the image
autoplay bool to autoplay youtube / Vimeo video
download bool/string Link to download the file. When set to a boolean value (true/false), the src is used as the download link.
controls bool works only for youtube videos, setting false will hide video controls

Gallery element attributes

These attributes can change the gallery element behaviour.

option required type description
gallery no array list of image objects that will be displayed in the gallery
image no object image object that will be displayed in the gallery
lazy-loading no bool whether images should be lazy loaded
preview-count no number number of images that should be displayed in the gallery

Events

SilentBox also fires several events that can be further used in your Vue.js application.

Event name description
silentbox-overlay-opened when the overlay is opened
silentbox-overlay-hidden when the overlay is closed (button or ESC key)
silentbox-overlay-next-item-displayed when the user moves to the next picture (arrow or key)
silentbox-overlay-prev-item-displayed when the user moves to the previous picture (arrow or key)

Open overlay programatically

SilentBox provides two options how to open the overlay programatically. If you need to open an existing gallery, the best option is to use the ref attribute and then call the method openOverlay on the $refs object in your method. See example:
index.html

<silent-box ref="silentbox" :gallery="gallery"></silent-box>
                
app.js

// ...
methods: {
    // the index parameter is optional, however it should be set if you're opening
    // the overlay on different position than the beginning of the gallery
    openOverlayProgramaticallyWithContext (item, index = 0) {
        this.$refs.silentbox.openOverlay(item, index)
    }
}
// ...
                

However, in case you just want to open an item without any context, it might be a better choice to call the global "open" method that SilentBox provides.

app.js

// ...
methods: {
    openOverlayProgramaticallyWithoutContext (item) {
        this.$silentbox.open(item)
    }
}
// ...
                

Upgrading from older version?

See the github README.md for guidance.