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

Security Considerations

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