Quick Start

Last updated: March 2, 2026

This guide gets you from a blank page to a working lightbox in under two minutes. If you haven’t installed Zoomora yet, start with the Installation guide first.

The Simplest Example

Here’s everything you need for a single working lightbox:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Page</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/zoomora/dist/zoomora.css">
</head>
<body>

  <img src="photo.jpg"
       data-src="photo.jpg"
       data-zoomora="my-gallery"
       alt="My photo">

  <script src="https://cdn.jsdelivr.net/npm/zoomora/dist/zoomora.umd.min.js"></script>
  <script>
    new Zoomora();
  </script>

</body>
</html>

Click the image and the lightbox opens. That’s it.

The Three Required Pieces

Every Zoomora image needs these three things:

1. data-src — the full-size image URL to show in the lightbox. This can be different from the src attribute, which is the thumbnail shown on the page.

data-src="photo-fullsize.jpg"

2. data-zoomora — a group name that connects images into a gallery. Images sharing the same value are grouped together and can be navigated with prev/next arrows and thumbnails.

data-zoomora="my-gallery"

3. new Zoomora() — initialises the plugin. Call this once after your images are in the DOM.

<script>
  new Zoomora();
</script>

Adding a Second Image

To create a gallery, add more images with the same data-zoomora value:

<img src="photo-1-thumb.jpg"
     data-src="photo-1-full.jpg"
     data-zoomora="my-gallery"
     alt="Photo 1">

<img src="photo-2-thumb.jpg"
     data-src="photo-2-full.jpg"
     data-zoomora="my-gallery"
     alt="Photo 2">

<img src="photo-3-thumb.jpg"
     data-src="photo-3-full.jpg"
     data-zoomora="my-gallery"
     alt="Photo 3">

<script>
  new Zoomora();
</script>

Zoomora automatically adds prev/next navigation, a thumbnail strip, and a counter (1 / 3, 2 / 3, etc.) for the group.

Adding a Caption

Add a data-caption attribute to any image to show a caption in the lightbox:

<img src="photo.jpg"
     data-src="photo.jpg"
     data-zoomora="my-gallery"
     data-caption="Golden hour at the coast"
     alt="Coastal photo">

Using Custom Options

Pass an options object to new Zoomora() to customise the behaviour:

new Zoomora({
  transition: 'slide',        // 'fade' (default) or 'slide'
  showThumbnails: true,       // show thumbnail strip
  showCounter: true,          // show image counter
  showZoom: true,             // show zoom button
  showFullscreen: true,       // show fullscreen button
  closeOnBackgroundClick: true // close when clicking outside image
});

You don’t need to pass all options — only the ones you want to change. Everything else falls back to its default value.

What Happens When You Click

When a user clicks an image with data-zoomora:

Zoomora finds all images in the same group on the page
Opens the lightbox at the clicked image
Builds the thumbnail strip from the group
Enables prev/next navigation between group items
Checks if the image is zoomable and enables zoom if so

Clicking outside the image, pressing Esc, or clicking the close button dismisses the lightbox.

Next Step

Read How It Works for a deeper understanding of grouping, the lightbox lifecycle, and how Zoomora scans the DOM — or jump straight to Image Gallery to start building real gallery layouts.

Quick Links