Lightbox Image Gallery

BS5 Lightbox is a pure JavaScript lightbox gallery component for Bootstrap 5, providing a beautiful modal overlay for viewing images in full size.

Overview

The lightbox plugin allows users to click on images to view them in a full-screen modal overlay with navigation controls. It's perfect for image galleries, product photos, screenshots, and any other scenario where users need to see images in detail.

Key Features

• Zero Dependencies: Only requires Bootstrap 5 (already included)
• Responsive: Works perfectly on all devices and screen sizes
• Keyboard Navigation: Use arrow keys to navigate, ESC to close
• Touch Support: Swipe gestures on mobile devices
• Gallery Mode: Group images and navigate between them
• Captions: Add descriptive text to your images
• Dark Mode: Automatically adapts to your current theme
• Lightweight: Fast loading and smooth animations

Installation

The lightbox is already included in UltraViolet and ready to use. The CSS and JavaScript are loaded via CDN in the plugin files.

<!-- CSS (in plugins.blade.php) -->
<link href="https://cdn.jsdelivr.net/npm/bs5-lightbox@1.8.3/dist/index.bundle.min.css" rel="stylesheet">

<!-- JavaScript (in cdn-scripts.blade.php) -->
<script src="https://cdn.jsdelivr.net/npm/bs5-lightbox@1.8.5/dist/index.bundle.min.js"></script>

Basic Usage

Single Image

To enable lightbox on a single image, wrap it in an anchor tag with data-toggle="lightbox":

<a href="path/to/large-image.jpg" data-toggle="lightbox" data-caption="My Image">
    <img src="path/to/thumbnail.jpg" class="img-fluid" alt="My Image">
</a>

Image Gallery

Group multiple images together using data-gallery="gallery-name" to enable navigation between images:

<div class="row">
    <div class="col-md-4">
        <a href="image1.jpg" data-toggle="lightbox" data-gallery="my-gallery" data-caption="Image 1">
            <img src="image1.jpg" class="img-fluid" alt="Image 1">
        </a>
    </div>
    <div class="col-md-4">
        <a href="image2.jpg" data-toggle="lightbox" data-gallery="my-gallery" data-caption="Image 2">
            <img src="image2.jpg" class="img-fluid" alt="Image 2">
        </a>
    </div>
    <div class="col-md-4">
        <a href="image3.jpg" data-toggle="lightbox" data-gallery="my-gallery" data-caption="Image 3">
            <img src="image3.jpg" class="img-fluid" alt="Image 3">
        </a>
    </div>
</div>

Data Attributes

The lightbox is configured using HTML5 data attributes:

Examples

Simple Image with Caption

<a href="asset-images-screenshot.png.html" data-toggle="lightbox" data-caption="Dashboard Screenshot">
    <img src="{{ asset('images/screenshot.png') }}" class="img-fluid" alt="Screenshot">
</a>

Gallery with Multiple Images

<div class="row g-3">
    @foreach($images as $image)
        <div class="col-md-4">
            <a href="image-gt-url.html" 
               data-toggle="lightbox" 
               data-gallery="product-gallery" 
               data-caption="{{ $image->title }}">
                <img src="{{ $image->thumbnail }}" class="img-fluid" alt="{{ $image->title }}">
            </a>
        </div>
    @endforeach
</div>

Advanced Example with All Options

<a href="large-image.jpg" 
   data-toggle="lightbox"
   data-gallery="my-gallery"
   data-caption="Product Photo"
   data-footer="Copyright © 2025 Your Company"
   data-max-width="1200">
    <img src="thumbnail.jpg" class="img-fluid" alt="Product">
</a>

Background Images

For elements using background images (like in the welcome page), wrap the element in an anchor tag:

<a href="asset-images-promo-dashboard.png.html" data-toggle="lightbox" data-caption="Dashboard Preview">
    <div style="height: 300px; background-image: url('{{ asset('images/promo/dashboard.png') }}'); 
                background-size: cover; background-position: center; cursor: pointer;"></div>
</a>

Keyboard Controls

When a lightbox is open, users can control it with their keyboard:

• Arrow Left/Right: Navigate to previous/next image in gallery
• ESC: Close the lightbox
• Home: Go to first image in gallery
• End: Go to last image in gallery

Mobile Support

The lightbox is fully responsive and supports touch gestures:

• Swipe Left: Next image
• Swipe Right: Previous image
• Tap Outside: Close lightbox

Dark Mode

The lightbox automatically detects your current Bootstrap theme (light/dark) and adjusts its appearance accordingly:

• Dark Mode: Modal backdrop and controls use dark colors
• Light Mode: Modal backdrop and controls use light colors

No additional configuration is required - it just works!

Best Practices

Image Optimization

1. Use Appropriate Sizes: Serve images at reasonable resolutions (1920px wide max for most cases)
2. Optimize Files: Compress images to reduce load times
3. Lazy Loading: Consider using lazy loading for galleries with many images

Accessibility

1. Alt Text: Always provide descriptive alt text for images
2. Captions: Use meaningful captions to provide context
3. Keyboard Navigation: The lightbox supports full keyboard navigation by default

Gallery Organization

1. Logical Groups: Use different gallery names for different sets of images
2. Consistent Naming: Use descriptive gallery names (e.g., data-gallery="product-photos")
3. Caption Quality: Write clear, informative captions

Initialization

The lightbox is automatically initialized on page load for all elements with data-toggle="lightbox". You don't need to write any JavaScript!

The initialization happens in the admin layout:

document.addEventListener('DOMContentLoaded', function() {
    document.querySelectorAll('[data-toggle="lightbox"]').forEach(el => {
        el.addEventListener('click', Lightbox.initialize);
    });
});

Troubleshooting

Images Not Opening in Lightbox

1. Verify the data-toggle="lightbox" attribute is present
2. Check that the href points to a valid image URL
3. Ensure the lightbox JavaScript is loaded (check browser console)

Gallery Navigation Not Working

1. Make sure all images in the gallery have the same data-gallery value
2. Verify images are in the correct DOM order
3. Check that each link has data-toggle="lightbox"

Dark Mode Not Applying

The lightbox reads the data-bs-theme attribute from your HTML element. Ensure your theme switching is working correctly:

<html data-bs-theme="dark">

Live Examples

Visit the Lightbox Component Page to see live examples and interactive demonstrations.

Browser Support

BS5 Lightbox supports all modern browsers:

• ✅ Chrome (latest 2 versions)
• ✅ Firefox (latest 2 versions)
• ✅ Safari (latest 2 versions)
• ✅ Edge (latest 2 versions)
• ✅ Mobile browsers (iOS Safari, Chrome Mobile)

Additional Resources

• BS5 Lightbox GitHub
• Bootstrap 5 Documentation
• Component Examples