Navigation Methods

Last updated: July 1, 2026

Navigation methods let you open, close, and move between lightbox items programmatically. These are the most commonly used API methods.

open(element)

Opens the lightbox at the specified DOM element. The element must be one that Zoomora recognises — it should match the selector option and have the required data attributes (data-src and data-zoomora, or href and data-lightbox for anchor mode).

const lightbox = new Zoomora();
const firstImage = document.querySelector('[data-zoomora="gallery"]');

lightbox.open(firstImage);

When open() is called, Zoomora finds all elements in the same group as the provided element, sets the starting index to that element’s position in the group, and opens the lightbox exactly as if the user had clicked it.

Opening the first image in a gallery:

const lightbox = new Zoomora();

document.getElementById('view-gallery-btn').addEventListener('click', () => {
  const firstImage = document.querySelector('[data-zoomora="portfolio"]');
  lightbox.open(firstImage);
});

Opening a specific image by index:

const lightbox = new Zoomora();
const images = document.querySelectorAll('[data-zoomora="gallery"]');

// Open the third image (index 2)
lightbox.open(images[2]);

openImage(images, opts)

Added in v1.3.0

Opens the lightbox programmatically with images that are not present in the DOM. Unlike open(), no trigger element or data-zoomora attribute is required — pass a URL directly and Zoomora handles the rest.

Accepts:

A single URL string
An array of URL strings (creates a synthetic gallery)
A config object with src, thumb, type, caption, and alt fields
An array of config objects

Options:

startIndex — zero-based index to open at when passing an array (default: 0)

Single image (paste as a code block):

lightbox.openImage('assets/images/photo.jpg');

With caption and alt text (paste as a code block):

lightbox.openImage({
  src: 'assets/images/photo.jpg',
  caption: 'Golden hour',
  alt: 'Landscape photo'
});

Synthetic gallery (paste as a code block):

lightbox.openImage(
  ['assets/images/a.jpg', 'assets/images/b.jpg', 'assets/images/c.jpg'],
  { startIndex: 1 }
);

Mixed gallery with video (paste as a code block):

lightbox.openImage([
  { src: 'assets/images/photo.jpg', caption: 'A photo' },
  {
    src: 'https://youtu.be/VIDEO_ID',
    type: 'video',
    thumb: 'assets/images/poster.jpg',
    caption: 'A video'
  }
]);

AJAX use case (paste as a code block):

document.getElementById('quick-view-btn').addEventListener('click', async () => {
  const data = await fetch('/api/product/42').then(r => r.json());
  lightbox.openImage({ src: data.fullImage, caption: data.title });
});

openImage() fires the onOpen callback just like open() does. All other navigation methods — next(), prev(), goTo(), close() — work normally on the resulting gallery.

close()

Closes the lightbox if it is currently open. Resets zoom and position state, restores body scroll, and fires the onClose callback.

lightbox.close();

Closing after a timeout:

lightbox.open(firstImage);

// Auto-close after 5 seconds
setTimeout(() => {
  lightbox.close();
}, 5000);

next()

Navigates to the next item in the current gallery group. Does nothing if the lightbox is on the last item.

lightbox.next();

External next button:

document.getElementById('my-next-btn').addEventListener('click', () => {
  lightbox.next();
});

Fires the onNext callback with the new index after navigating.

prev()

Navigates to the previous item in the current gallery group. Does nothing if the lightbox is on the first item.

lightbox.prev();

Fires the onPrev callback with the new index after navigating.

goTo(index)

Jumps directly to a specific item by its zero-based index. Does nothing if the index is out of range.

// Jump to the first item
lightbox.goTo(0);

// Jump to the fourth item
lightbox.goTo(3);

Building an external thumbnail strip that controls the lightbox:

const lightbox = new Zoomora();
const externalThumbs = document.querySelectorAll('.my-thumb');

externalThumbs.forEach((thumb, index) => {
  thumb.addEventListener('click', () => {
    if (lightbox.isOpen()) {
      lightbox.goTo(index);
    } else {
      const images = document.querySelectorAll('[data-zoomora="gallery"]');
      lightbox.open(images[index]);
    }
  });
});

Checking State Before Navigating

Use isOpen() before calling navigation methods to avoid errors when the lightbox is not active:

if (lightbox.isOpen()) {
  lightbox.next();
}

// Safe goTo with bounds check
const total = lightbox.getTotalItems();
const targetIndex = 2;

if (lightbox.isOpen() && targetIndex < total) {
  lightbox.goTo(targetIndex);
}

Next Step

Read Control Methods to learn how to toggle zoom, fullscreen, thumbnails, and auto-hide from your own code.

Quick Links