Bootstrap-Based Image Lightbox for Modern Web App – AvalynxLightbox

AvalynxLightbox is a simple, lightweight image lightbox library that uses Bootstrap’s modal component to display images in a modal view with customizable options.

Features:

• Customizable Behavior: Configure opacity, z-index, close button labels, and interaction modes through straightforward options.
• Click-Outside Closing: Allow users to dismiss the lightbox by clicking outside the image or through an explicit close button.
• Callback Support: Execute custom functions when the lightbox closes, enabling you to trigger side effects or analytics.
• Minimal Footprint: No jQuery, no framework requirements, no extra DOM manipulation libraries.

How to use it:

1. To get started, make sure you have the latest Bootstrap framework installed in your project.

2. Install & import the AvalynxLightbox library.

# NPM
$ npm install avalynx-lightbox

import { AvalynxLightbox } from 'avalynx-lightbox';

<!-- OR -->
<script src="/dist/js/avalynx-lightbox.js"></script>

3. Initialize AvalynxLightbox. The library listens for elements matching your CSS selector and transforms them into lightbox triggers.

<img 
  src="path/to/thumbnail.jpg" 
  data-src="path/to/full-image.jpg" 
  class="avalynx-lightbox" 
  alt="An example image">

new AvalynxLightbox('.avalynx-lightbox', {
    // options here
})

The script automatically looks for a data-src attribute on your image tags to load the full-resolution image into the lightbox. If it’s not present, it will use the src attribute.

4. Pass the following options to customize the behavior of the image lightbox.

• closeable (boolean): If true, a close button is displayed. Defaults to true.
• closeOnClickOutside (boolean): If true, clicking the backdrop closes the lightbox. Defaults to true.
• onClose (function): A callback function that runs when the lightbox is closed. Defaults to null.
• opacity (number): Sets the background opacity from 0 to 100. Defaults to 80.
• zIndex (number): The CSS z-index for the lightbox overlay. Defaults to 1500.
• closeButtonLabel (string): The aria-label text for the close button for accessibility. Defaults to 'Close'.

new AvalynxLightbox('.avalynx-lightbox', {
    closeable: true,
    closeOnClickOutside: true,
    opacity: 80,
    zIndex: 1500,
    onClose: () => console.log('Lightbox closed')
})

FAQs:

Q: Does AvalynxLightbox support image galleries with next/previous buttons?
A: No, it’s designed to handle one image at a time. It doesn’t include gallery navigation features. For that, you’d need a more feature-rich galley lightbox library.

Q: Can I use it without Bootstrap?
A: No. The library is fundamentally built on Bootstrap’s modal system and CSS. It will not function correctly without Bootstrap 5.3+ included in your project.

Q: How can I customize the look of the lightbox beyond the available options?
A: Since it uses Bootstrap’s modal classes, you can override the CSS for classes like .modal-dialog, .modal-content, and the custom classes the library adds.

Q: Can I use this with images loaded dynamically after page load?
A: The current implementation binds events when you instantiate AvalynxLightbox. If you’re adding images dynamically through AJAX or JavaScript frameworks, you’ll need to reinitialize the library after adding new elements or delegate events manually.

Q: What happens if I set closeOnClickOutside to false but closeable to false as well?
A: Users won’t be able to close the lightbox through normal means. This is generally a bad idea for UX, but you could use the callback mechanism to programmatically close it. The library will let you do this, but the user experience suffers significantly.

Q: How does opacity work with the z-index setting?
A: These are independent properties. The opacity controls only the background overlay transparency. The z-index controls where the entire lightbox sits in the stacking context. Set z-index higher if your lightbox appears behind sticky headers or fixed elements.