This article explains what happens under the hood when Zoomora initialises, how grouping works, and the full lifecycle of a lightbox session. You don’t need to know this to use Zoomora — but understanding it helps when building more complex setups or debugging unexpected behaviour.
Initialisation
When you call new Zoomora(), the plugin does two things:
1. Injects the lightbox DOM Zoomora creates a single <div id="zoomoraLightbox"> and appends it to <body>. This happens once and the element stays in the DOM for the lifetime of the page — it’s reused every time the lightbox opens rather than being created and destroyed on each click.
2. Binds a document-level click listener Instead of attaching a click handler to every individual image, Zoomora listens for clicks on the entire document and checks whether the clicked element matches the selector option (default: [data-zoomora]). This means images added to the DOM dynamically after initialisation — for example, loaded via AJAX — are automatically supported without needing to reinitialise.
How Grouping Works
The data-zoomora attribute serves as a group identifier. When an image is clicked, Zoomora queries the entire document for all elements sharing the same data-zoomora value:
document.querySelectorAll('[data-zoomora="my-gallery"]')
This becomes the current gallery. The clicked image’s position within that list determines the starting index. Navigation (prev/next) moves through the list in DOM order — top to bottom, left to right as they appear in the HTML.
Each value is an independent gallery. Images with different data-zoomora values are completely separate and never mixed:
<!-- Gallery A — 3 items -->
<img data-zoomora="landscapes" data-src="lake.jpg" ...>
<img data-zoomora="landscapes" data-src="mountain.jpg" ...>
<img data-zoomora="landscapes" data-src="forest.jpg" ...>
<!-- Gallery B — 2 items, completely separate -->
<img data-zoomora="portraits" data-src="person-1.jpg" ...>
<img data-zoomora="portraits" data-src="person-2.jpg" ...>
Single images work the same way — give them a unique data-zoomora value and they open as a solo lightbox with no navigation arrows or thumbnails.
data-src vs src
Zoomora always reads the full-size image from data-src. The src attribute is what the browser displays on the page (your thumbnail) and is used as the thumbnail image inside the lightbox strip.
<img src="photo-small.jpg" <!-- shown on page, used as thumbnail -->
data-src="photo-large.jpg" <!-- opened in lightbox -->
data-zoomora="gallery">
If data-src is not present, Zoomora falls back to src. This means you can use the same image for both, but for best performance you should always provide a smaller thumbnail for src and the full-size version for data-src.
The Lightbox Lifecycle
Every time a user opens the lightbox, the following sequence runs:
Click on image
↓
Zoomora finds the group (querySelectorAll)
↓
Sets currentIndex to clicked image position
↓
Lightbox overlay fades in, body scroll is locked
↓
Image loads and animates in (fade or slide)
↓
Thumbnails, counter, caption, and nav buttons update
↓
Zoom availability is checked for the current image
↓
User navigates / zooms / goes fullscreen
↓
User closes (Esc, close button, or background click)
↓
Overlay fades out, body scroll is restored
↓
Zoom and position state resets for next open
How Zoom Detection Works
When an image finishes loading inside the lightbox, Zoomora calls checkZoomability(). This compares the image’s natural (actual file) dimensions against its rendered size in the lightbox:
- If the natural size is meaningfully larger than the rendered size, zoom is enabled and the zoom cursor appears.
- If the image already fits the viewport at or near its natural size, zoom is quietly disabled — no cursor, no zoom button behaviour.
This is why an image displayed at width="250px" on the page might not zoom inside the lightbox — if the lightbox renders it at a size close to its natural dimensions, there’s nothing to zoom into. Remove fixed width attributes from your <img> tags and control sizing with CSS for best results.
How Content is Loaded
Each time the lightbox navigates to an image, Zoomora clears the slides container and renders fresh content. For images, it creates an <img> element, sets its src, and waits for the onload event before animating it in and hiding the loading spinner.
For YouTube URLs, Zoomora’s convertToEmbedUrl() method automatically transforms the URL before rendering — standard youtube.com/watch?v= and short youtu.be/ formats are both handled, including timestamp parameters.
Event Handling & Cleanup
Zoomora tracks every event listener it adds in an internal Map. When you call destroy(), all listeners are removed cleanly and the lightbox DOM is removed from <body>. This makes it safe to use in single-page applications where components mount and unmount.
Next Step
Now that you understand how Zoomora works, head to Image Gallery to start building real gallery layouts, or read about Video Support if you need to include videos in your lightbox.