SkyLightbox - a flexible lightbox plugin for Vue.js 2, build on v-img

!important

This module only provides a complete barebone ligthbox setup/display, thus encouraging you to make your own lightbox display with the module's provided functionality. The reason for this is to allow full author flexibility across multiple projects and to keep the bundle size to a minimum and not become biased towards the design/content of a lightbox overlay.

Getting started

Quick start

In order to make the plugin work we need to download necessary dependencies.

yarn add sky-lightbox

Next thing to do is adding the plugin to the Vue. Shown with dummy ligthbox componenet setup.

// Setup your preferred lightbox overlay component.
import { SkyLightboxMixin } from 'sky-lightbox';

export default {
    name: 'LigthboxComponent',
    mixins: [SkyLightboxMixin],
    mounted() {
        console.log('Custom lightbox component loaded');
    },
};

// Import Vue, sky-lightbox and custom lightbox component
import Vue from 'vue'
import SkyLightbox from 'sky-lightbox'

import LigthboxComponent from './LigthboxComponent.vue';

// Loading the plugin into the Vue.
Vue.use(SkyLightbox, { lightbox: LigthboxComponent });

Configurations

Snippet with default settings;

const config = {
  // Use `alt` attribute as gallery slide title
  altAsTitle: false,
  // Event listener to open gallery will be applied to <img> element
  openOn: 'click',
  // Component to use as lightbox overlay instead of provided compoenent
  lightbox: SkyLightbox, // Internal component name.
}

Vue.use(SkyLightbox, config);

Usage

Basic example

Simple initialization to lightbox a single image

<img
    v-sky-lightbox
    src="image.png"
>

OR

<img
    v-sky-lightbox="{
        src: 'image.png',
    }"
    src="image.png"
>

Group images in lightbox slider example

Simple initialization to lightbox an image which is part of a gallery / group.

<img
    v-sky-lightbox:group-name
    src="image.png"
>

OR

<img
    v-sky-lightbox="{
        src: 'image.png',
        group: 'group-name',
    }"
    src="image.png"
>

The Lightbox Component

When v-sky-lightbox is used, the set lightbox component will be added to the bottom of the page. No matter how many groups are made, only one component will be made and reused for all galleries. This means that you cannot nest a lightbox inside a lightbox easily.

Plugin

v-sky-lightbox

Single source of input for enabling lightbox overlay for a given image.

Inline directive settings

| Option | Description | Default value | Data type | | ------ | ----------- | ------------- | --------- | | group | The same as directive argument, but could be set dynamically | directive argument or undefined | string | | src | Image source that will be displayed in gallery | src attribute value from html tag | string | | title | Caption that will be displayed | empty string or value of the alt attribute, if altAsTitle is true | string | | openOn | Event listener to open gallery will be applied to <img>. Available options are 'dblclick', 'mouseover' and all native JS events. | 'click' if another not stated when initializing plugin | string | | opened | Function that will be executed on gallery open | undefined | function | | closed | Function that will be executed on gallery close | undefined | function | | changed(imageIndex) | Function that will be executed when switching between images in gallery | undefined | function |

• Any of these options except opened, closed, changed functions and openOn property could be changed at runtime.

Component / Mixin

As this module is only a barebone setup, it only has a few vital pieces of data and methods to be used for the basic functionality of the lightbox. However, the module also supplies behind-the-scenes functionality for normal use cases.

Functionality

| Functionality | Description | | ------------- | ----------- | | Closing | The lightbox component will automatically close if either 'Q' (for 'quit') or Escape is pressed on the keyboard. It will also close when a scroll is initiated. | | Next image | The lightbox will move to the next image if either the Right Arrow or 'L' is pressed on the keyboard. | | Previous image | The lightbox will move to the previous image if either the Left Arrow or 'H' is pressed on the keyboard. | | Show UI | The component can hide the galleri UI until the mouse has moved. See the visibleUI in the Data section below. |

Data

| Data | Description | Data type | | ---- | ----------- | --------- | | closed | Whether or not the gallery is currently closed | boolean | | currentGroup | The group assigned to the current gallery, if any | string | | images | An array with the image or images currently in the gallery | array | | currentImageIndex | The currently displayed image's index | number | | titles | The title values of the images currently in the gallery | array | | visibleUI | Whether or not the gallery UI should be shown or not | boolean |

Note that this data is available to you, but not necessarily something you always want to use. The visibleUI variable, for example, can be used to hide and show the UI based on mouse movement, but you may also simply not use it, and have the UI always visble, or make your own system for extended functionality.

Methods

| Method | Description | Arguments | Return | | ------ | ----------- | --------- | ------ | | close() | Close the gallery | n/a | void | | prev() | Go to the previous image in the gallery | n/a | void | | next() | Go to the next image in the gallery | n/a | void | | select(index) | Jump to a specific image in the gallery | index: The index of the image to jump to | void | | showUI() | Force visibleUI to true and restart the disappearence timeout | n/a | void |

Todo

• Add data clearance delay to closing