Documentation

Installation

Using npm

npm install simple-lightbox-gallery

Using CDN

<!-- Add to your HTML head -->
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/simple-lightbox-gallery.css">

<!-- Add before closing body tag -->
<script src="https://unpkg.com/[email protected]/dist/simple-lightbox-gallery.js"></script>

Usage

Basic Setup: Create a container with your images and initialize the gallery.

Basic Implementation

<!-- HTML Structure -->
<div class="gallery">
    <img src="image1.jpg" alt="Image 1">
    <img src="image2.jpg" alt="Image 2">
    <img src="image3.jpg" alt="Image 3">
</div>

<script>
    // Initialize gallery
    const gallery = new SimpleLightboxGallery({
        containerClass: 'gallery',
        showCaption: true
    });
</script>

Configuration Options

Option Type Default Description
containerClass string 'gallery' Class name of the gallery container
showThumbnails boolean false Show thumbnail navigation
showCaption boolean true Show image captions (uses alt text)
captionPosition string 'bottom' Position of caption ('top' or 'bottom')
animation string 'fade' Animation type ('fade' or 'none')
animationSpeed number 300 Animation duration in milliseconds
zoomEnabled boolean true Enable image zoom functionality
zoomLevel number 1.5 Maximum zoom level
slideshow boolean false Enable slideshow functionality
slideshowSpeed number 3000 Slideshow interval in milliseconds

Examples

Basic Gallery

new SimpleLightboxGallery({
    containerClass: 'gallery',
    showCaption: true
});

Gallery with Thumbnails

new SimpleLightboxGallery({
    containerClass: 'gallery',
    showThumbnails: true,
    showCaption: true,
    captionPosition: 'bottom'
});

Slideshow Gallery

new SimpleLightboxGallery({
    containerClass: 'gallery',
    slideshow: true,
    slideshowSpeed: 3000,
    showCaption: true
});

Custom Animation

new SimpleLightboxGallery({
    containerClass: 'gallery',
    animation: 'fade',
    animationSpeed: 500,
    showCaption: true
});

API Methods

Method Arguments Description
openLightbox(index) number Opens lightbox at specified image index
closeLightbox() none Closes the lightbox
nextImage() none Shows next image
prevImage() none Shows previous image
toggleZoom() none Toggles image zoom
toggleSlideshow() none Toggles slideshow play/pause
destroy() none Removes event listeners and cleans up

Usage Example

const gallery = new SimpleLightboxGallery({
    containerClass: 'gallery'
});

// Open specific image
gallery.openLightbox(2);

// Start slideshow
gallery.toggleSlideshow();

// Cleanup on unmount
gallery.destroy();

Events

Event Arguments Description
onOpen index: number Triggered when lightbox is opened
onClose none Triggered when lightbox is closed
onChange index: number Triggered when active image changes
onZoom isZoomed: boolean Triggered when zoom state changes

Event Handling Example

new SimpleLightboxGallery({
    containerClass: 'gallery',
    onOpen: (index) => console.log(`Opened image ${index}`),
    onChange: (index) => console.log(`Changed to image ${index}`),
    onClose: () => console.log('Lightbox closed'),
    onZoom: (isZoomed) => console.log(`Zoom ${isZoomed ? 'enabled' : 'disabled'}`)
});

Framework Integration

React

React Integration: Create a reusable component and handle cleanup properly. 
import { useEffect } from 'react';
import SimpleLightboxGallery from 'simple-lightbox-gallery';
import 'simple-lightbox-gallery/dist/simple-lightbox-gallery.css';

function Gallery() {
    useEffect(() => {
        const gallery = new SimpleLightboxGallery({
            containerClass: 'gallery',
            showCaption: true
        });
        
        return () => gallery.destroy();
    }, []);

    return (
        <div className="gallery">
            <img src="image1.jpg" alt="Image 1" />
            <img src="image2.jpg" alt="Image 2" />
            <img src="image3.jpg" alt="Image 3" />
        </div>
    );
}

Vue

Vue Integration: Compatible with Vue 2 and Vue 3. 
<template>
    <div class="gallery">
        <img v-for="(image, index) in images" 
             :key="index"
             :src="image.src"
             :alt="image.alt">
    </div>
</template>

<script>
import { onMounted, onBeforeUnmount } from 'vue';
import SimpleLightboxGallery from 'simple-lightbox-gallery';
import 'simple-lightbox-gallery/dist/simple-lightbox-gallery.css';

export default {
    name: 'Gallery',
    setup() {
        let gallery = null;

        onMounted(() => {
            gallery = new SimpleLightboxGallery({
                containerClass: 'gallery',
                showCaption: true
            });
        });

        onBeforeUnmount(() => {
            if (gallery) gallery.destroy();
        });

        return {};
    }
}
</script>

Next.js

Important: Use 'use client' directive for client-side rendering. 
'use client';

import { useEffect } from 'react';
import SimpleLightboxGallery from 'simple-lightbox-gallery';
import 'simple-lightbox-gallery/dist/simple-lightbox-gallery.css';

export default function Gallery() {
    useEffect(() => {
        const gallery = new SimpleLightboxGallery({
            containerClass: 'gallery',
            showCaption: true
        });
        return () => gallery.destroy();
    }, []);

    return (
        <div className="gallery">
            <img src="image1.jpg" alt="Image 1" />
            <img src="image2.jpg" alt="Image 2" />
            <img src="image3.jpg" alt="Image 3" />
        </div>
    );
}

Angular

Angular Integration: Use lifecycle hooks for initialization and cleanup. 
import { Component, OnInit, OnDestroy } from '@angular/core';
import SimpleLightboxGallery from 'simple-lightbox-gallery';
import 'simple-lightbox-gallery/dist/simple-lightbox-gallery.css';

@Component({
    selector: 'app-gallery',
    template: `
        <div class="gallery">
            <img *ngFor="let image of images"
                 [src]="image.src"
                 [alt]="image.alt">
        </div>
    `
})
export class GalleryComponent implements OnInit, OnDestroy {
    private gallery: any;

    ngOnInit() {
        this.gallery = new SimpleLightboxGallery({
            containerClass: 'gallery',
            showCaption: true
        });
    }

    ngOnDestroy() {
        if (this.gallery) {
            this.gallery.destroy();
        }
    }
}

Browser Support

Note: The gallery uses modern JavaScript features and CSS Grid. For older browsers, consider using a polyfill.

Accessibility

Features

Keyboard Navigation

Key Action
←/→ Navigate between images
Esc Close lightbox
Space Play/pause slideshow
F Toggle fullscreen
Z Toggle zoom

Troubleshooting

Common Issues

Images Not Loading

Solution: Ensure images are fully loaded before initializing the gallery. 
window.addEventListener('load', () => {
    new SimpleLightboxGallery({
        containerClass: 'gallery'
    });
});

Mobile Touch Issues

Solution: Make sure touch events are not being prevented by other scripts.

Framework Integration Issues

Important: Always clean up the gallery instance when unmounting components to prevent memory leaks.