Vanilla JavaScript Gallery Lightbox with Touch Support – Obsidium

Obsidium is an accessible, mobile-friendly JavaScript lightbox library that displays your images and rich text in a gallery popup with zoom/navigation controls, smooth transitions, and thumbnail previews.

Features:

• Zero Dependencies: Runs as a standalone library with no external requirements.
• Touch Support: Handles swipe gestures for navigation and closing on mobile devices.
• Theme System: Includes light and dark themes with support for custom styling.
• Variable Zoom: Switches between multiple zoom levels with drag-to-pan controls.
• ️ Keyboard Controls: Responds to arrow keys, space, escape, and zoom shortcuts.
• ️ Thumbnail Strip: Displays a navigable strip of preview images below the main viewer.
• Smart Preloading: Loads adjacent slides in advance to eliminate loading delays.
• Animation Library: 8 built-in transition effects between slides.
• Text Slides: Accepts HTML and plain text content alongside images.
• EXIF Display: Shows camera metadata when the optional exifr library is included.
• Accessibility: Implements proper focus management and keyboard navigation.

Use Cases:

• Portfolio Galleries: Display high-resolution photography or design work with zoom controls and EXIF data.
• Product Catalogs: Show product images with thumbnail navigation and custom descriptions.
• Documentation Sites: Present screenshots and diagrams with text explanations in a unified viewer.
• Content Management Systems: Attach a lightbox to dynamically loaded image galleries without framework dependencies.

How To Use It:

1. Download the zip and load the necessary JS/CSS files from the dist folder.

<link rel="stylesheet" href="/dist/obsidium.css" />
<script src="/dist/obsidium.js"></script>

2. Load an animation CSS you prefer:

<link rel="stylesheet" href="dist/animations/fade.css">
<link rel="stylesheet" href="dist/animations/flip.css">
<link rel="stylesheet" href="dist/animations/zoom.css">
<link rel="stylesheet" href="dist/animations/bounce.css">
<link rel="stylesheet" href="dist/animations/rotate.css">
<link rel="stylesheet" href="dist/animations/stack.css">
<link rel="stylesheet" href="dist/animations/long-slide.css">

3. Create a container element with preview images. Add a data-src attribute to each image that points to the full-resolution version.

<div id="gallery">
  <img src="/thumbnails/photo1.jpg" data-src="/images/photo1.jpg" />
  <img src="/thumbnails/photo2.jpg" data-src="/images/photo2.jpg" />
  <img src="/thumbnails/photo3.jpg" data-src="/images/photo3.jpg" />
</div>

4. Initialize the lightbox by passing the container ID to the Obsidium constructor and calling the init method. When you click any preview image, the lightbox opens and displays the full-resolution version.

new Obsidium("gallery").init()

5. You can attach the lightbox to any HTML elements by specifying data attributes for preview and full-size sources. Pass the element type as the second constructor argument.

<div id="custom-gallery">
  <a href="#" data-preview="/thumbnails/photo1.jpg" data-src="/images/photo1.jpg">View Photo 1</a>
  <a href="#" data-preview="/thumbnails/photo2.jpg" data-src="/images/photo2.jpg">View Photo 2</a>
  <a href="#" data-preview="/thumbnails/photo3.jpg" data-src="/images/photo3.jpg" data-title="Sunset">View Photo 3</a>
</div>

new Obsidium("custom-gallery", "a").init()

6. For cases where you need manual control over when the lightbox opens, create an image or text array and trigger it through any user interaction.

const mixedContent = [
  { src: "https://picsum.photos/1600/1200?random=20", preview: "https://picsum.photos/800/600?random=20", title: "Start with an Image" },
  { element: "html-slide-content" }, // ID of the hidden DOM element
  { src: "https://picsum.photos/1600/1200?random=21", preview: "https://picsum.photos/800/600?random=21", title: "End with an Image" }
];
let mixedInstance = null;
document.getElementById('open-mixed').addEventListener('click', () => {
  if (mixedInstance) {
    mixedInstance.destroy();
  }
  mixedInstance = new Obsidium(mixedContent).init({
    theme: "dark",
    thumbnails: false // Thumbnails might look weird with text slides unless handled carefully
  });
  mixedInstance.open(0);
});

7. The default package includes the short-slide animation. Additional effects require importing separate CSS files from the animations directory as introduced above. Available animations include flip, bounce, fade, long-slide, rotate, stack, and zoom.

You can create custom animations by following the naming conventions in the existing animation stylesheets.

new Obsidium("gallery").init({
  animation: "flip"
})

8. Include the exifr library to extract and display camera information in the info panel. Images must be served from the same origin or have CORS headers configured properly.

<script src="https://cdn.jsdelivr.net/npm/exifr/dist/lite.umd.js"></script>

9. All configuration options:

• zoom: Toggles the zoom function.
• zoomLevels: Sets the magnification steps for zooming in.
• counter: Shows the current slide index.
• preload: Loads upcoming slides in the background.
• title: Renders the title text below the image.
• info: Toggles the EXIF information panel.
• hide: Controls the visibility of UI overlays.
• loadExif: Fetches metadata using the exifr library.
• thumbnails: Toggles the thumbnail navigation strip.
• thumbnailsSize: Sets the dimensions for thumbnail images.
• thumbnailsGap: Sets the gap between thumbnails.
• clickOutsideToClose: Closes the viewer upon background clicks.
• translateOnHorizontalSwipe: Moves the image horizontally during swipe gestures.
• translateOnVerticalSwipe: Moves the image vertically during close gestures.
• animation: Defines the transition effect between slides.
• theme: Applies the visual color scheme.

const insntance = new Obsidium("gallery").init({
  zoom: true,
  zoomLevels: [1.5, 2, 2.5, 3],
  counter: true,
  preload: true,
  title: true,
  info: true,
  hide: true,
  loadExif: true,
  thumbnails: true,
  thumbnailsSize: '3rem',
  thumbnailsGap: '0.25rem',
  clickOutsideToClose: true,
  translateOnHorizontalSwipe: true,
  translateOnVerticalSwipe: true,
  animation: 'short-slide',
  theme: 'dark'
})

10. Instance methods.

• init(options): Starts the instance with configuration settings.
• open(index, direction): Activates the viewer at a specific slide.
• close(): Shuts down the viewer and resets focus.
• next(): Advances to the following slide.
• prev(): Returns to the preceding slide.
• hideInterface(): Removes UI controls from the view.
• showInterface(): Restores UI controls to the view.
• refreshElements(): Rebuilds the slide list from the DOM.
• updateOptions(newOptions): Merges new settings into the current configuration.
• destroy(): Removes the instance and cleans up event listeners.

Alternatives:

• PhotoSwipe: A JavaScript gallery component focused on mobile performance and touch interactions.
• GLightbox: A lightweight lightbox that handles images, videos, and inline content with minimal configuration.
• Best Gallery Lightbox:  A constantly updated list of the 10 best Vanilla JavaScript and Pure CSS-powered Gallery Lightbox Libraries to present your images & products elegantly.

FAQs:

Q: Can I use Obsidium with server-side rendered applications?
A: Yes. Initialize the lightbox after the DOM loads by placing the initialization code in a DOMContentLoaded event listener or at the end of your body tag.

Q: How do I integrate Obsidium with a dynamic image gallery that updates after page load?
A: Call the refreshElements method after adding or removing images from the gallery container.

Q: Does Obsidium work on mobile devices and tablets?
A: Yes. The library handles touch events for swiping between slides, pinch-to-zoom gestures, and swipe-down-to-close actions. The interface adapts automatically to different screen sizes and orientations.

Q: Can I display content other than images in the lightbox?
A: Yes. Pass HTML elements or plain text strings in your slide data array. The component displays text slides without zoom controls or thumbnails since these features apply specifically to images.

The post Vanilla JavaScript Gallery Lightbox with Touch Support – Obsidium appeared first on CSS Script.