Vue 2 reached End of Life on December 31, 2023. This package targets Vue 2.7.16, the final stable release. For long-term support, consider migrating to Vue 3.

Installation

NPM

npm install vlightbox

Register the Component

Global Registration:

import Vue from 'vue';
import lightbox from 'vlightbox';

Vue.use(lightbox);

Local Registration:

import { Lightbox } from 'vlightbox';

export default {
  components: {
    Lightbox
  }
}

TypeScript:

import { Lightbox, LightboxImage } from 'vlightbox';

const images: LightboxImage[] = [
  { id: 1, src: '/path/to/image.jpg', caption: 'My caption' }
];

Usage

<template>
  <lightbox 
    :images="images"
    :currentImage.sync="currentImage"
    :overlayActive.sync="overlayActive"
  >
    <div v-for="(image, index) in images" :key="image.id">
      <img :src="image.src" @click="openLightbox(index)">
    </div>
  </lightbox>
</template>

<script>
export default {
  data() {
    return {
      images: [
        { id: 1, src: 'path/to/image1.jpg', caption: 'First image' },
        { id: 2, src: 'path/to/image2.jpg', caption: 'Second image' },
        { id: 3, src: 'path/to/image3.jpg' }
      ],
      currentImage: 0,
      overlayActive: false
    }
  },
  methods: {
    openLightbox(index) {
      this.currentImage = index;
      this.overlayActive = true;
    }
  }
}
</script>

Props

Prop	Type	Default	Description
`images`	`Array`	`[]`	Array of image objects with `src` and optional `caption`, `downloadable`, `downloadUrl`
`currentImage`	`Number`	`0`	Index of the currently displayed image (supports `.sync`)
`overlayActive`	`Boolean`	`false`	Whether the lightbox overlay is visible (supports `.sync`)
`loop`	`Boolean`	`true`	Loop back to first/last image at gallery ends
`nav`	`Boolean`	`true`	Show next, prev, and close buttons
`caption`	`Boolean`	`true`	Display image captions
`download`	`Boolean`	`false`	Show download button for images
`resetstyles`	`Boolean`	`false`	Remove default gallery styling (overlay unaffected)

Image Object Properties

Property	Type	Required	Description
`src`	`String`	✓	URL of the image
`id`	`String/Number`		Unique identifier
`caption`	`String`		Caption text for the image
`downloadable`	`Boolean`		Per-image download override (takes precedence over global `download` prop)
`downloadUrl`	`String`		Alternative URL for downloading (e.g., high-res version)

Events

Event	Payload	Description
`update:currentImage`	`Number`	Emitted when navigating between images
`update:overlayActive`	`Boolean`	Emitted when overlay opens/closes
`close`	-	Emitted when the lightbox is closed
`download`	`{ index, image }`	Emitted when download button is clicked

Keyboard Shortcuts

Key	Action
`←` Left Arrow	Previous image
`→` Right Arrow	Next image
`Esc`	Close lightbox

Development

# Install dependencies
npm install

# Run dev server
npm start

# Run tests
npm test

# Build for production
npm run build

When running npm audit, you may see vulnerabilities reported in Vue 2 ecosystem packages (vue, vue-template-compiler, postcss, @vue/test-utils). These are development-only dependencies and do not affect consumers of this package:

These vulnerabilities exist in Vue 2 core, which reached EOL on December 31, 2023
The published npm package does not include these dev dependencies
Users installing vlightbox via npm only receive the compiled bundle
Fixing these would require migrating to Vue 3 (breaking change)

If your project requires zero vulnerabilities, consider using a Vue 3-compatible lightbox alternative.

Changelog

v2.1.0

Converted to TypeScript with full type definitions
Updated to Vue 2.7.16 (final Vue 2 release)
Updated build tooling: Webpack 5, Babel 7, Jest 29
Fixed memory leak: Event listeners now properly removed on component destroy
Improved prop handling: All props now have proper types and defaults
Added events: Components now emit events for parent synchronization
Security updates: All dependencies updated to fix known vulnerabilities
Added comprehensive unit tests with @vue/test-utils
Exported LightboxImage interface for TypeScript users

v2.0.1

Initial stable release for Vue 2.3+

License

MIT Oliver Taylor