Lightbox2 (lokesh/lightbox2)

Lightbox2

https://github.com/lokesh/lightbox2
Admin
Lightbox2 is a lightweight JavaScript library that overlays images on top of the current page with a...

Tokens:7,388
Snippets:51
Trust Score:9.1
Update:3 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# 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
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body>
  <!-- Single image with lightbox -->
  <a href="images/photo.jpg" data-lightbox="image-1">
    <img src="images/photo-thumb.jpg" alt="My Photo">
  </a>

  <!-- Single image with caption -->
  <a href="images/sunset.jpg"
     data-lightbox="image-2"
     data-title="Beautiful sunset over the ocean">
    <img src="images/sunset-thumb.jpg" alt="Sunset">
  </a>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
</body>
</html>
```

### Image Gallery (Set) Implementation

Group multiple images into a gallery by using the same `data-lightbox` value across multiple anchor tags.

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body>
  <div class="gallery">
    <!-- All images with data-lightbox="vacation" form a gallery -->
    <a href="images/beach-1.jpg"
       data-lightbox="vacation"
       data-title="Day 1: Arrival at the beach">
      <img src="images/beach-1-thumb.jpg" alt="Beach Day 1">
    </a>

    <a href="images/beach-2.jpg"
       data-lightbox="vacation"
       data-title="Day 2: Snorkeling adventure">
      <img src="images/beach-2-thumb.jpg" alt="Beach Day 2">
    </a>

    <a href="images/beach-3.jpg"
       data-lightbox="vacation"
       data-title="Day 3: Sunset dinner">
      <img src="images/beach-3-thumb.jpg" alt="Beach Day 3">
    </a>
  </div>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
</body>
</html>
```

### Legacy rel Attribute Implementation

Use the `rel` attribute for backwards compatibility or when working with older codebases.

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body>
  <!-- Single image using rel -->
  <a href="images/single.jpg" rel="lightbox">
    <img src="images/single-thumb.jpg" alt="Single">
  </a>

  <!-- Gallery using rel with grouping -->
  <a href="images/gallery-1.jpg" rel="gallery-group" title="First image">
    <img src="images/gallery-1-thumb.jpg" alt="Gallery 1">
  </a>
  <a href="images/gallery-2.jpg" rel="gallery-group" title="Second image">
    <img src="images/gallery-2-thumb.jpg" alt="Gallery 2">
  </a>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
</body>
</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
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body>
  <a href="images/photo.jpg" data-lightbox="custom">
    <img src="images/photo-thumb.jpg" alt="Photo">
  </a>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
  <script>
    lightbox.option({
      'wrapAround': true,
      'disableScrolling': true,
      'albumLabel': "Photo %1 / %2"
    });
  </script>
</body>
</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
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
  <style>
    .controls { margin: 20px 0; }
    .controls button { padding: 10px 20px; margin: 5px; }
  </style>
</head>
<body>
  <div class="controls">
    <button id="open-gallery">Open Gallery</button>
    <button id="close-gallery">Close Gallery</button>
    <button id="goto-third">Go to Third Image</button>
  </div>

  <div style="display: none;">
    <a href="images/1.jpg" data-lightbox="api-gallery" id="first-image">
      <img src="images/1-thumb.jpg" alt="Image 1">
    </a>
    <a href="images/2.jpg" data-lightbox="api-gallery">
      <img src="images/2-thumb.jpg" alt="Image 2">
    </a>
    <a href="images/3.jpg" data-lightbox="api-gallery">
      <img src="images/3-thumb.jpg" alt="Image 3">
    </a>
  </div>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
  <script>
    $('#open-gallery').on('click', function() {
      var $firstLink = $('#first-image');
      lightbox.start($firstLink);
    });

    $('#close-gallery').on('click', function() {
      lightbox.end();
    });

    $('#goto-third').on('click', function() {
      lightbox.changeImage(2);
    });
  </script>
</body>
</html>
```

### Alt Text and Accessibility

Provide alternative text for images to improve accessibility.

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body>
  <a href="images/product.jpg"
     data-lightbox="products"
     data-alt="Red leather handbag with gold hardware"
     data-title="Premium Leather Handbag - $299">
    <img src="images/product-thumb.jpg"
         alt="Red leather handbag thumbnail">
  </a>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
</body>
</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
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body>
  <!-- Unsafe: user-submitted title with HTML -->
  <a href="images/user-photo.jpg"
     data-lightbox="user-content"
     data-title="User photo <script>alert('XSS')</script>">
    <img src="images/user-photo-thumb.jpg" alt="User photo">
  </a>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
  <script>
    // Sanitize titles to prevent XSS
    lightbox.option({
      'sanitizeTitle': true  // Strips HTML tags
    });
  </script>
</body>
</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
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body>
  <!-- Large image that will be scaled to fit viewport -->
  <a href="images/huge-photo-4000x3000.jpg"
     data-lightbox="responsive">
    <img src="images/huge-photo-thumb.jpg" alt="High resolution photo">
  </a>

  <!-- SVG image (automatically maximized in viewport) -->
  <a href="images/diagram.svg" data-lightbox="responsive">
    <img src="images/diagram-thumb.png" alt="Diagram">
  </a>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
  <script>
    lightbox.option({
      'fitImagesInViewport': true,
      'maxWidth': 1200,
      'positionFromTop': 80
    });
  </script>
</body>
</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
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body>
  <p>Use arrow keys to navigate, ESC to close</p>

  <a href="images/slide1.jpg" data-lightbox="presentation"
     data-title="Slide 1 - Introduction">
    <img src="images/slide1-thumb.jpg" alt="Slide 1">
  </a>
  <a href="images/slide2.jpg" data-lightbox="presentation"
     data-title="Slide 2 - Overview">
    <img src="images/slide2-thumb.jpg" alt="Slide 2">
  </a>
  <a href="images/slide3.jpg" data-lightbox="presentation"
     data-title="Slide 3 - Conclusion">
    <img src="images/slide3-thumb.jpg" alt="Slide 3">
  </a>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
  <script>
    lightbox.option({
      'wrapAround': true,
      'showImageNumberLabel': true,
      'albumLabel': 'Slide %1 of %2'
    });
  </script>
</body>
</html>
```

### Touch Device Navigation

Configure navigation controls for touch-enabled devices.

```javascript
lightbox.option({
  // Always show navigation arrows on touch devices
  'alwaysShowNavOnTouchDevices': true
});
```

```html
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body>
  <div class="mobile-gallery">
    <a href="images/mobile-1.jpg" data-lightbox="mobile-set">
      <img src="images/mobile-1-thumb.jpg" alt="Photo 1">
    </a>
    <a href="images/mobile-2.jpg" data-lightbox="mobile-set">
      <img src="images/mobile-2-thumb.jpg" alt="Photo 2">
    </a>
    <a href="images/mobile-3.jpg" data-lightbox="mobile-set">
      <img src="images/mobile-3-thumb.jpg" alt="Photo 3">
    </a>
  </div>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
  <script>
    lightbox.option({
      'alwaysShowNavOnTouchDevices': true,
      'wrapAround': true,
      'disableScrolling': true
    });
  </script>
</body>
</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
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body>
  <div class="portfolio">
    <a href="images/project-1.jpg" data-lightbox="portfolio"
       data-title="E-commerce Website">
      <img src="images/project-1-thumb.jpg" alt="Project 1">
    </a>
    <a href="images/project-2.jpg" data-lightbox="portfolio"
       data-title="Mobile App Design">
      <img src="images/project-2-thumb.jpg" alt="Project 2">
    </a>
    <a href="images/project-3.jpg" data-lightbox="portfolio"
       data-title="Brand Identity">
      <img src="images/project-3-thumb.jpg" alt="Project 3">
    </a>
  </div>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
  <script>
    lightbox.option({
      'albumLabel': 'Project %1 of %2',
      'showImageNumberLabel': true,
      'fadeDuration': 300
    });
  </script>
</body>
</html>
```

### Disable Page Scrolling

Prevent background page scrolling when lightbox is open.

```javascript
lightbox.option({
  'disableScrolling': true
});
```

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body style="height: 3000px; padding: 20px;">
  <h1>Long Page Content</h1>
  <p>Scroll down to see the effect...</p>

  <a href="images/photo.jpg" data-lightbox="fixed">
    <img src="images/photo-thumb.jpg" alt="Photo">
  </a>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
  <script>
    lightbox.option({
      'disableScrolling': true  // Body won't scroll while lightbox is open
    });
  </script>
</body>
</html>
```

### 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
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/css/lightbox.min.css">
</head>
<body>
  <h2>Fast Animations</h2>
  <a href="images/fast.jpg" data-lightbox="fast">
    <img src="images/fast-thumb.jpg" alt="Fast animation demo">
  </a>

  <script src="dist/js/lightbox-plus-jquery.min.js"></script>
  <script>
    lightbox.option({
      'fadeDuration': 200,
      'imageFadeDuration': 200,
      'resizeDuration': 300
    });
  </script>
</body>
</html>
```

## 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.