Spotlight JS

Spotlight JS is a tiny, dependency-free image viewer that instantly turns images on any webpage into a polished full-screen gallery. It provides smooth animations, trackpad gestures, touch, keyboard shortcuts and fullscreen support — all wired up automatically with zero configuration.

Try the live demo

Why Spotlight

• Lightweight and self-contained — drop in spotlight.min.js and it just works.
• Automatic grouping — images inside <article> or elements with the .gallery class become collections.
• Fast, fluid animations — hardware-accelerated transitions for a native feel.
• Accessible — ARIA live region and sensible focus management.

Features

• Automatic detection of images inside article and .gallery
• Fullscreen viewer with smooth transitions
• Zoom (buttons, mouse wheel, trackpad, pinch)
• Pan by dragging
• Trackpad gestures
• Touch support
• Keyboard navigation (Arrow keys + optional VIM-like keys)
• Captions from figcaption, alt, or data-caption
• Dark / light theme support via prefers-color-scheme
• No external dependencies

Controls

Experience full control via keyboard, mouse, touch, and trackpad.

Control	Example
Previous Image - Keyboard: ArrowLeft / H - Mouse: Left arrow button - Touch: Swipe Right - Trackpad: Two fingers swipe left
Next Image - Keyboard: ArrowRight / L - Mouse: Right arrow button - Touch: Swipe Left - Trackpad: Two fingers swipe right
Zoom In - Keyboard: + / = - Mouse: Zoom in button / Ctrl + Scroll Up - Touch: Pinch Out - Trackpad: Pinch/zoom gesture
Zoom Out - Keyboard: - / _ - Mouse: Zoom out button / Ctrl + Scroll Down - Touch: Pinch In - Trackpad: Pinch/zoom gesture
Toggle Fullscreen - Keyboard: F - Mouse: Fullscreen button	(No gesture)
Close Spotlight - Keyboard: Escape - Mouse: Close (cross) button - Touch: Swipe Down - Trackpad: Two fingers swipe down

Installation

Include the built script on your page:

<script src="spotlight.min.js"></script>

Spotlight initializes automatically when a user clicks an image inside an article or a .gallery element.

Usage

Write normal HTML — Spotlight works with simple images or semantic markup:

<article>
  <figure>
    <img src="photo1.jpg" alt="Mountains at sunrise" />
    <figcaption>Mountains at sunrise</figcaption>
  </figure>

  <img src="photo2.jpg" alt="Forest trail" />
</article>

Or use a gallery:

<div class="gallery">
  <img src="a.jpg" />
  <img src="b.jpg" />
  <img src="c.jpg" />
</div>

Click any image to open the viewer.

Development

To contribute or build Spotlight from source:

1. Clone the repository:

   git clone https://github.com/jarpex/spotlight-js.git
   cd spotlight-js

2. Install dependencies:

   npm install

3. Build the project:

   Spotlight offers two build modes:

   • Optimized Build (Default):

     npm run build

     Creates a highly compressed bundle in dist/spotlight.min.js. This mode aggressively renames CSS classes and IDs to short tokens (e.g., a, b) to minimize size. Warning: This may cause conflicts if your page uses similar short class names or IDs.

   • Safe Build:

     npm run build:safe

     Creates a standard minified bundle that preserves original class names and IDs. Use this version to avoid conflicts with other scripts or styles on your page, or if you need to use the Programmatic API.

Programmatic API

Note: The programmatic API is available only in the safe build.

The standard npm run build command uses aggressive minification that renames classes and symbols, making the API inaccessible. To use the API, build the project with npm run build:safe.

Static Methods

• Spotlight.open(collectionIndex, itemIndex) — Opens the gallery. Defaults to the first image in the first collection if no indices are provided.
• Spotlight.rescan() — Re-scans the DOM for new images. Call this after dynamically adding content to the page.
• Spotlight.getCapturedErrors() — Retrieves a list of non-fatal errors logged by the library.
• Spotlight.clearCapturedErrors() — Clears the list of captured errors.

Properties

• Spotlight.instance — Returns the active Spotlight instance, or null if the gallery has not been initialized.
• Spotlight.debug — Enables verbose console logging when set to true. Only functional in development builds.

Instance Methods

Access the instance via Spotlight.instance.

• instance.attachImage(element, collectionIndex, itemIndex) — Manually registers an image element with the Spotlight gallery.

Example

// Enable debug mode
Spotlight.debug = true;

// Open the first image in the first collection
Spotlight.open(0, 0);

// Manually attach an image
const instance = Spotlight.instance;
if (instance) {
  const img = document.querySelector('#my-image');
  instance.attachImage(img, 0, 0);
}

License

Spotlight JS is released under the MIT License — see LICENSE. It bundles Tabler Icons (MIT) as noted in LICENSE.tabler-icons.