# Lightbox2 Documentation ## Introduction Lightbox2 is a lightweight JavaScript library designed to overlay images on top of the current webpage. Originally created by Lokesh Dhakar, it has become one of the most widely used image overlay solutions on the web. The library provides an elegant way to display images in a modal-like interface with smooth animations, keyboard navigation, and support for image galleries. The library is built on jQuery and follows a simple, declarative approach using HTML data attributes. It automatically detects links with specific attributes and transforms them into lightbox-enabled elements. Lightbox2 supports both individual images and image sets (galleries), includes responsive viewport fitting, SVG support, and provides extensive customization options through configuration parameters. The library handles all the complexity of positioning, sizing, preloading, and transitioning between images while maintaining accessibility features like keyboard navigation and focus management. ## API Documentation and Examples ### Basic Single Image Implementation Initialize Lightbox2 by including the CSS and JavaScript files, then add the `data-lightbox` attribute to any anchor tag pointing to an image. ```html

``` ### Image Gallery (Set) Implementation Group multiple images into a gallery by using the same `data-lightbox` value across multiple anchor tags. ```html

``` ### Legacy rel Attribute Implementation Use the `rel` attribute for backwards compatibility or when working with older codebases. ```html

``` ### Custom Configuration Options Configure Lightbox2 behavior by passing options to the Lightbox constructor or modifying defaults. ```javascript // Method 1: Configure via JavaScript after DOM loads $(document).ready(function() { lightbox.option({ 'resizeDuration': 200, 'wrapAround': true, 'disableScrolling': true, 'fitImagesInViewport': true, 'imageFadeDuration': 300, 'fadeDuration': 300, 'positionFromTop': 100, 'showImageNumberLabel': true, 'alwaysShowNavOnTouchDevices': true, 'albumLabel': "Image %1 of %2", 'maxWidth': 1200, 'maxHeight': 800, 'sanitizeTitle': false }); }); // Method 2: Access and modify defaults before initialization Lightbox.defaults.fadeDuration = 400; Lightbox.defaults.wrapAround = true; // Complete HTML example with custom configuration ``` ```html

``` ### Programmatic Control Control lightbox behavior programmatically using the API methods. ```javascript // Access the lightbox instance var lb = lightbox; // Programmatically trigger lightbox on specific element var $link = $('a[data-lightbox="programmatic"]').first(); lb.start($link); // Close/end the lightbox programmatically lb.end(); // Change to specific image in current album by index lb.changeImage(2); // Navigate to third image (0-indexed) // Enable keyboard navigation lb.enableKeyboardNav(); // Disable keyboard navigation lb.disableKeyboardNav(); // Update configuration on the fly lb.option({ 'fadeDuration': 500, 'imageFadeDuration': 500 }); // Complete example: Custom gallery with controls ``` ```html

``` ### Alt Text and Accessibility Provide alternative text for images to improve accessibility. ```html

``` ### XSS Protection with Title Sanitization Enable title sanitization when displaying user-generated content to prevent XSS attacks. ```javascript // Enable sanitization for untrusted content lightbox.option({ 'sanitizeTitle': true }); // Example with user-generated titles ``` ```html

``` ### Module Loading (AMD/CommonJS/ES6) Use Lightbox2 in various module systems for modern JavaScript applications. ```javascript // AMD (RequireJS) define(['jquery', 'lightbox'], function($, lightbox) { lightbox.option({ 'wrapAround': true }); }); // CommonJS (Node.js/Browserify) var $ = require('jquery'); var lightbox = require('lightbox2'); lightbox.option({ 'fadeDuration': 400, 'imageFadeDuration': 400 }); // ES6 Module (with webpack/bundler) import 'lightbox2/dist/css/lightbox.min.css'; import lightbox from 'lightbox2'; lightbox.option({ 'resizeDuration': 500, 'wrapAround': true }); // NPM Installation // npm install lightbox2 --save ``` ### NPM Package Integration Complete example of integrating Lightbox2 into a modern Node.js/webpack project. ```javascript // Install via npm // npm install lightbox2 jquery --save // main.js import $ from 'jquery'; import 'lightbox2/dist/css/lightbox.min.css'; import lightbox from 'lightbox2'; // Configure lightbox $(document).ready(function() { lightbox.option({ 'resizeDuration': 300, 'wrapAround': true, 'disableScrolling': true, 'albumLabel': 'Image %1 of %2' }); }); // Usage in component export function initGallery(selector) { $(selector).on('click', function(e) { e.preventDefault(); lightbox.start($(this)); }); } ``` ```json // package.json { "name": "my-app", "version": "1.0.0", "dependencies": { "jquery": "^3.6.0", "lightbox2": "^2.11.5" }, "devDependencies": { "webpack": "^5.0.0", "css-loader": "^6.0.0", "style-loader": "^3.0.0" } } ``` ### Responsive Images with Viewport Fitting Configure how Lightbox2 handles image sizing in different viewports. ```javascript lightbox.option({ // Automatically resize images to fit viewport 'fitImagesInViewport': true, // Set maximum dimensions 'maxWidth': 1200, 'maxHeight': 900, // Position from top of viewport 'positionFromTop': 50 }); ``` ```html

``` ### Keyboard Navigation Control Lightbox2 supports keyboard navigation with ESC, left arrow, and right arrow keys. ```javascript // Keyboard shortcuts are enabled by default: // - ESC: Close lightbox // - Left Arrow: Previous image in gallery // - Right Arrow: Next image in gallery // Enable wrap-around for keyboard navigation lightbox.option({ 'wrapAround': true // Allows cycling from last to first image }); // Disable keyboard navigation temporarily lightbox.disableKeyboardNav(); // Re-enable keyboard navigation lightbox.enableKeyboardNav(); ``` ```html

Use arrow keys to navigate, ESC to close

``` ### Touch Device Navigation Configure navigation controls for touch-enabled devices. ```javascript lightbox.option({ // Always show navigation arrows on touch devices 'alwaysShowNavOnTouchDevices': true }); ``` ```html

``` ### Custom Album Label Formatting Customize the image counter label format displayed in galleries. ```javascript // Default format lightbox.option({ 'albumLabel': 'Image %1 of %2' // Shows "Image 1 of 5" }); // Custom formats lightbox.option({ 'albumLabel': '%1 / %2' // Shows "1 / 5" }); lightbox.option({ 'albumLabel': 'Photo %1 from %2' // Shows "Photo 1 from 5" }); // Hide image numbering completely lightbox.option({ 'showImageNumberLabel': false }); ``` ```html

``` ### Disable Page Scrolling Prevent background page scrolling when lightbox is open. ```javascript lightbox.option({ 'disableScrolling': true }); ``` ```html

Long Page Content

Scroll down to see the effect...

``` ### Animation Duration Configuration Control the speed of various animations in the lightbox. ```javascript lightbox.option({ // Fade duration for overlay and lightbox appearance 'fadeDuration': 600, // milliseconds // Image fade-in duration 'imageFadeDuration': 600, // milliseconds // Container resize animation duration 'resizeDuration': 700 // milliseconds }); // Fast animations lightbox.option({ 'fadeDuration': 200, 'imageFadeDuration': 200, 'resizeDuration': 300 }); // Slow, smooth animations lightbox.option({ 'fadeDuration': 1000, 'imageFadeDuration': 1000, 'resizeDuration': 1200 }); ``` ```html

Fast Animations

``` ## Summary Lightbox2 serves as a versatile solution for displaying images in web applications, from simple product photography to complex image galleries and portfolios. Common use cases include e-commerce product viewers, photography portfolios, documentation with screenshot galleries, real estate listings, blog post image galleries, and mobile-responsive image presentations. The library's declarative HTML-based approach makes it accessible to developers of all skill levels while providing sufficient programmatic control for advanced implementations. The integration pattern is straightforward: include the CSS and JavaScript files, add data attributes to image links, and optionally configure behavior through the JavaScript API. The library automatically handles initialization, event binding, and cleanup. For modern applications using build tools like webpack or Rollup, Lightbox2 can be imported as an NPM module and integrated into component-based architectures. The minimal dependencies (only jQuery) and small footprint make it suitable for projects ranging from simple static websites to complex single-page applications, while its MIT license ensures it can be freely used in both commercial and open-source projects.