Modern JavaScript Lightbox with Zoom & Gallery – Zoomora

Zoomora is a modern JavaScript lightbox library that creates interactive image and video galleries with built-in zoom, fullscreen capabilities, thumbnail navigation, and smooth transitions.

It automatically detects whether images can be zoomed based on their dimensions, implements pan-and-drag functionality for navigated zoomed content, and provides auto-hide controls for an immersive viewing experience.

Features:

• Core Functionality: Zoomora supports both image galleries and video content, including YouTube embeds and local video files in MP4, WebM, and OGG formats.
• Zoom and Navigation: The library features smart zoom detection, pan-and-drag controls for zoomed images, and a configurable maximum zoom scale with support for scroll wheel navigation.
• User Interface: Thumbnail strips provide quick navigation between gallery items, with optional auto-hide controls, fullscreen mode, and customizable transition effects including fade and slide animations.
• Accessibility and Controls: Full keyboard navigation supports arrow keys for image browsing, escape key for closing, and shortcut keys for zoom, fullscreen, and thumbnail toggling.
• Technical Specifications: The library requires no external dependencies, integrates with vanilla JavaScript and modern frameworks, and provides extensive callback functions for lifecycle events.

See It In Action:

Use Cases:

• Portfolio and Photography Websites: Photographers and designers can display high-resolution work samples in galleries where users can zoom into fine details. The thumbnail strip lets visitors quickly browse through collections, while the fullscreen mode provides an immersive viewing experience that showcases image quality without competing page elements.
• Product Catalogs and E-commerce: Online stores can implement Zoomora to display product images from multiple angles, giving customers the ability to examine details before purchasing. The zoom functionality replicates the in-store experience of inspecting merchandise closely, while the gallery format organizes variant images or supplementary product views in a single interface.
• Documentation and Tutorial Content: Technical documentation often requires detailed screenshots or diagrams that benefit from zoom capabilities. Zoomora allows users to view full-resolution images without leaving the documentation page, maintaining context while providing the clarity needed to follow complex instructions or examine interface details.
• Mixed Media Presentations: Content sites that combine images with video content can use Zoomora’s video support to create cohesive galleries. The library handles both YouTube embeds and locally hosted video files, providing a consistent interface regardless of media type and allowing creators to mix formats within a single gallery group.

Keyboard Shortcuts:

Key	Action
←	Previous image
→	Next image
Esc	Close lightbox / Exit fullscreen
Z	Toggle zoom
F	Toggle fullscreen
T	Toggle thumbnails

How to use it:

1. Install & download Zoomora with NPM.

# NPM
$ npm install zoomora

2. Include Zoomora’s JavaScript and CSS files on your web page.

<link rel="stylesheet" href="dist/zoomora.css">
<script src="dist/zoomora.umd.min.js"></script>

3. Add the data-zoomora attribute to your image elements, assigning a unique group ID to create a gallery.

<!-- Image -->
<img src="https://picsum.photos/seed/landscape1/800/600"
 alt="A random landscape image"
 data-src="https://picsum.photos/seed/landscape1/1600/1200"
 data-caption="A beautiful landscape scene."
 data-zoomora="demo-gallery"
 loading="lazy">

<!-- Video -->
<img src="https://picsum.photos/seed/video_thumb/800/600"
  alt="YouTube Video Thumbnail"
  data-src="https://www.youtube.com/watch?v=2pg4QOqW-aI"
  data-type="video"
  data-caption="An embedded YouTube video."
  data-zoomora="demo-gallery"
  loading="lazy">
<!-- More Items Here -->

4. Initialize Zoomora and done.

document.addEventListener('DOMContentLoaded', function () {
  new Zoomora({
    gallery: 'demo-gallery'
  });
});

5. Customize the behavior and appearance of the lightbox.

• selector: (String) The CSS selector for lightbox trigger elements. Default: '[data-zoomora]'.
• showCounter: (Boolean) Toggles the display of the image counter (e.g., “1 / 5”). Default: true.
• showThumbnails: (Boolean) Toggles the visibility of the thumbnail navigation strip. Default: true.
• showFullscreen: (Boolean) Toggles the fullscreen button. Default: true.
• showZoom: (Boolean) Toggles the zoom button. Default: true.
• transition: (String) Sets the transition effect between items, either ‘fade’ or ‘slide’. Default: 'fade'.
• useHref: (Boolean) If true, uses the href attribute for the media source instead of data-src. Default: false.
• maxZoomScale: (Number) Defines the maximum zoom level for an image. Default: 3.
• zoomStep: (Number) Controls the zoom increment when using the scroll wheel. Default: 0.1.
• animationDuration: (Number) The duration of transition animations in milliseconds. Default: 300.
• showAutoHideToggle: (Boolean) Toggles the button to enable or disable auto-hiding of controls. Default: true.
• autoHideDelay: (Number) The delay in milliseconds before controls automatically hide. Default: 3000.
• autoHideEnabled: (Boolean) Determines if the auto-hide feature is enabled by default. Default: false.
• onOpen: (Function) A callback function that executes when the lightbox opens. Default: null.
• onClose: (Function) A callback function that executes when the lightbox closes. Default: null.
• onNext: (Function) A callback that runs when navigating to the next item. Default: null.
• onPrev: (Function) A callback that runs when navigating to the previous item. Default: null.

new Zoomora({
  selector: '[data-zoomora]',
  showCounter: true,
  showThumbnails: true,
  showFullscreen: true,
  showZoom: true,
  transition: 'fade',
  useHref: false,
  maxZoomScale: 3,
  zoomStep: 0.1,
  animationDuration: 300,
  showAutoHideToggle: true,
  autoHideDelay: 3000,
  autoHideEnabled: false,
});

6. Callback functions

new Zoomora({
  onOpen: (element, index) => {
    console.log('Opened lightbox at index:', index);
  },
  onClose: (index) => {
    console.log('Closed lightbox, was viewing index:', index);
  },
  onNext: (index) => {
    console.log('Navigated to next item:', index);
  },
  onPrev: (index) => {
    console.log('Navigated to previous item:', index);
  }
});

7. API methods.

const lightbox = new Zoomora();

// Navigate
lightbox.next();           // Go to next item
lightbox.prev();           // Go to previous item
lightbox.goTo(2);          // Go to specific index

// Controls
lightbox.open(element);    // Open lightbox with element
lightbox.close();          // Close lightbox
lightbox.toggleZoom();     // Toggle zoom
lightbox.toggleFullscreen(); // Toggle fullscreen
lightbox.toggleThumbnails(); // Toggle thumbnails
lightbox.toggleAutoHide(); // Toggle auto-hide controls

// State
lightbox.isOpen();         // Check if open
lightbox.getCurrentIndex(); // Get current index
lightbox.getTotalItems();  // Get total items

// Management
lightbox.refresh();        // Refresh gallery items
lightbox.updateOptions({   // Update options
  transition: 'slide'
});
lightbox.destroy();        // Clean up and remove

8. Override the default CSS variables to create your own styles.

/* Override CSS variables */:root {
  --zoomora-overlay-bg: rgba(0, 0, 0, 0.95);
  --zoomora-control-bg: rgba(255, 255, 255, 0.1);
  --zoomora-control-hover: rgba(255, 255, 255, 0.2);
}

/* Custom styles */.zoomora {
  /* Your custom styles */}

9. Some implementations require using anchor tags instead of direct image attributes. Set the useHref option to true and use the Zoomora.bind() method with a selector matching your anchor elements. This pattern works well for progressive enhancement scenarios where you want functional links that open images in a new tab when JavaScript fails to load.

const lightbox = Zoomora.bind('a[data-lightbox]', {
  useHref: true
});

<a href="full-image.jpg" data-lightbox="gallery">
  <img src="thumbnail.jpg" alt="Image">
</a>

FAQs:

Q: Can Zoomora handle dynamically added images after page load?
A: Yes. Call the refresh() method on your lightbox instance after adding new images to the DOM. This method rescans for elements matching your selector and attaches event listeners to new items. You can automate this by calling refresh in your dynamic content loading callbacks or after AJAX operations complete.

Q: How does zoom detection work for determining if an image is zoomable?
A: Zoomora compares the natural dimensions of an image against its displayed dimensions in the lightbox. If the image’s actual resolution exceeds what fits in the viewport, the library enables zoom controls. This prevents zoom functionality from appearing on images that are already displayed at full size or smaller, which would result in pixelation.

Q: What happens if a YouTube video URL is invalid or the video is deleted?
A: The library creates the iframe embed with the extracted video ID, but YouTube will display its standard error message within the iframe if the video is unavailable. Zoomora does not perform URL validation before creating embeds, so you need to validate YouTube URLs in your application code if you want to prevent loading invalid videos.

Q: Can I use multiple independent Zoomora instances with different configurations on the same page?
A: Yes. Create separate instances with different selector options to target different gallery groups. Each instance maintains its own configuration and state, so you can have one gallery with thumbnails enabled and another with thumbnails hidden, or use different transition effects for different content sections.

Q: Does the library handle images with different aspect ratios in the same gallery?
A: Zoomora adjusts the display size for each image independently to fit within the viewport while maintaining aspect ratio. When navigating between images with different dimensions, the lightbox resizes smoothly based on your configured animation duration. Thumbnail dimensions remain consistent regardless of source image aspect ratios.

Q: What happens to video playback when navigating away from a video item?
A: The library stops video playback when users navigate to a different gallery item or close the lightbox. For YouTube embeds, this occurs automatically when the iframe is removed from the DOM. Local video elements receive a pause command before being removed. This prevents videos from continuing to play audio in the background.

Q: How does Zoomora handle images that fail to load?
A: The library does not include built-in error handling for failed image loads. The browser’s default broken image icon will appear in the lightbox if a source URL returns a 404 or fails to load. Implement error handling by listening for error events on your image elements and either providing fallback sources or removing items from galleries that fail to load.

Related Resources:

• 10 Best Gallery Lightbox Libraries In Pure JavaScript/CSS
• 10 Best Free Modal Libraries For Vanilla JavaScript And CSS

The post Modern JavaScript Lightbox with Zoom & Gallery – Zoomora appeared first on CSS Script.