Configuration Overview

Last updated: March 2, 2026

Zoomora is initialised with an optional configuration object. All options have sensible defaults so you can call new Zoomora() with no arguments and get a fully working lightbox. Pass only the options you want to change.

new Zoomora({
  transition: 'slide',
  showThumbnails: false
});

Full Options Reference

Option	Type	Default	Description
`selector`	String	`'[data-zoomora]'`	CSS selector for lightbox trigger elements
`showCounter`	Boolean	`true`	Show the image counter (e.g. 2 / 5)
`showThumbnails`	Boolean	`true`	Show the thumbnail strip at the bottom
`showZoom`	Boolean	`true`	Show the zoom button
`showFullscreen`	Boolean	`true`	Show the fullscreen button
`showAutoHideToggle`	Boolean	`true`	Show the auto-hide controls toggle button
`transition`	String	`'fade'`	Transition effect: `'fade'` or `'slide'`
`useHref`	Boolean	`false`	Read image URL from `href` instead of `data-src`
`maxZoomScale`	Number	`3`	Maximum zoom scale multiplier
`zoomStep`	Number	`0.1`	Zoom increment per scroll wheel step
`animationDuration`	Number	`300`	Transition animation duration in milliseconds
`closeOnBackgroundClick`	Boolean	`true`	Close lightbox when clicking the dark overlay
`autoHideEnabled`	Boolean	`false`	Start with auto-hide controls enabled
`autoHideDelay`	Number	`3000`	Milliseconds of inactivity before controls hide
`onOpen`	Function	`null`	Callback fired when the lightbox opens
`onClose`	Function	`null`	Callback fired when the lightbox closes
`onNext`	Function	`null`	Callback fired when navigating to the next item
`onPrev`	Function	`null`	Callback fired when navigating to the previous item

Setting Options at Initialisation

Pass all your options once when creating the instance:

const lightbox = new Zoomora({
  selector: '[data-zoomora]',
  transition: 'fade',
  animationDuration: 400,
  showCounter: true,
  showThumbnails: true,
  showZoom: true,
  showFullscreen: true,
  showAutoHideToggle: false,
  closeOnBackgroundClick: true,
  maxZoomScale: 3,
  autoHideEnabled: false,
  autoHideDelay: 3000,
  onOpen: (element, index) => {
    console.log('Opened:', index);
  },
  onClose: (index) => {
    console.log('Closed at:', index);
  }
});

Updating Options After Initialisation

Use updateOptions() to change options on a live instance without reinitialising:

const lightbox = new Zoomora();

// Later — update one or more options
lightbox.updateOptions({
  transition: 'slide',
  closeOnBackgroundClick: false
});

Only the options you pass are updated. Everything else stays as it was.

Note that updateOptions() does not re-render the lightbox DOM — options like showZoom and showThumbnailsthat affect the HTML structure must be set at initialisation time to take effect correctly.

Using Multiple Instances

If you need different configurations for different sets of images on the same page, create multiple instances with different selectors:

// Minimal lightbox for hero images
new Zoomora({
  selector: '[data-zoomora="hero"]',
  showCounter: false,
  showThumbnails: false,
  showAutoHideToggle: false
});

// Full-featured lightbox for the main gallery
new Zoomora({
  selector: '[data-zoomora="gallery"]',
  transition: 'slide',
  autoHideEnabled: true,
  autoHideDelay: 4000
});

Each instance manages its own set of elements and has its own lightbox overlay. Both can be open independently — though in practice only one is visible at a time since each locks body scroll on open.

Default Values

If you want to inspect the full defaults object in code, access it via the static property:

console.log(Zoomora.defaults);

This returns the complete defaults object and is useful when building wrapper utilities or debugging configuration issues.

Next Step

The following articles cover each configuration group in detail with examples for the most common use cases:

Display Options — showCounter, showThumbnails, showZoom, showFullscreen, showAutoHideToggle
Behaviour Options — transition, animationDuration, closeOnBackgroundClick, maxZoomScale
Auto-Hide Controls — autoHideEnabled, autoHideDelay, showAutoHideToggle
Callbacks — onOpen, onClose, onNext, onPrev

Quick Links