Control Methods

Last updated: March 2, 2026

Control methods let you toggle UI states programmatically — zoom, fullscreen, thumbnails, and auto-hide. These mirror the buttons in the lightbox header but can be triggered from your own code at any time.

toggleZoom()

Cycles the current image to the next zoom level. Zoom levels progress through 1.5x, 2x, 3x, and 100% actual size, then return to fit-to-screen. Does nothing if the current item is not a zoomable image.

const lightbox = new Zoomora();

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

Calling toggleZoom() has the same effect as the user clicking the zoom button in the header or pressing the Z keyboard shortcut.

Note: Zoom availability depends on the image being larger than its rendered size in the lightbox. If the image does not qualify for zoom, toggleZoom() returns silently without doing anything.

toggleFullscreen()

Enters fullscreen mode if not currently fullscreen, or exits if already in fullscreen. Uses the native browser Fullscreen API with a CSS fallback.

lightbox.toggleFullscreen();

Equivalent to the user clicking the fullscreen button or pressing F.

Entering fullscreen on open:

const lightbox = new Zoomora({
  onOpen: () => {
    lightbox.toggleFullscreen();
  }
});

Note: The Fullscreen API requires a user gesture to activate in most browsers. Calling toggleFullscreen()inside an event handler (like onClick) works fine. Calling it outside a user gesture context (like a setTimeout) may be blocked by the browser.

toggleThumbnails()

Shows or hides the thumbnail strip at the bottom of the lightbox. Does nothing if there is only one item in the current gallery.

lightbox.toggleThumbnails();

Equivalent to the user clicking the thumbnails button in the header or pressing T.

Hiding thumbnails for a cleaner initial view:

const lightbox = new Zoomora({
  onOpen: () => {
    // Start with thumbnails hidden, user can toggle
    if (lightbox.getTotalItems() > 1) {
      lightbox.toggleThumbnails();
    }
  }
});

toggleAutoHide()

Enables auto-hide if currently disabled, or disables it if currently enabled. When enabling, starts the idle timer immediately. When disabling, stops the timer and shows the controls.

lightbox.toggleAutoHide();

Equivalent to the user clicking the auto-hide toggle button in the header.

Enabling auto-hide after a delay:

const lightbox = new Zoomora();

lightbox.open(firstImage);

// Enable auto-hide 2 seconds after opening
setTimeout(() => {
  lightbox.toggleAutoHide();
}, 2000);

Combining Control Methods

Build a custom external control panel that mirrors the lightbox buttons:

const lightbox = new Zoomora({ showAutoHideToggle: false });

document.getElementById('ext-zoom').addEventListener('click', () => {
  lightbox.toggleZoom();
});

document.getElementById('ext-fullscreen').addEventListener('click', () => {
  lightbox.toggleFullscreen();
});

document.getElementById('ext-thumbnails').addEventListener('click', () => {
  lightbox.toggleThumbnails();
});

document.getElementById('ext-autohide').addEventListener('click', () => {
  lightbox.toggleAutoHide();
});

Next Step

Read Instance Methods to learn how to read state, update options, and manage the lightbox instance lifecycle.

Quick Links