vlightbox

Simple native Vue.js lightbox component

Demo

https://olitaylor.github.io/vlightbox/

---

Compatibility

Vue 2.7.x (final Vue 2 release)

Note

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
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
resetstyles	Boolean	false	Remove default gallery styling (overlay unaffected)

---

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

---

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

---

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