Lightbox

A fully declarative lightbox. Add data-wf-lightbox to any trigger element and the JS handles the rest — no markup beyond the trigger is required. Supports images , native video ( .mp4 / .webm ), YouTube , Vimeo , and iframes . The media type is detected automatically from the URL; use data-wf-type to force it.

Basic

Import the module once. All [data-wf-lightbox] triggers are wired automatically on DOMContentLoaded .

JS Copy

import './wf-lightbox.js'

HTML Copy

<!-- Image: src comes from href -->
<a href="photo-full.jpg" data-wf-lightbox data-wf-caption="Forest trail">
  <img src="photo-thumb.jpg" alt="Forest trail">
</a>

<!-- Image: src explicit (for non-<a> triggers) -->
<button data-wf-lightbox data-wf-src="photo-full.jpg" data-wf-type="image">
  View photo
</button>

Gallery

Give multiple triggers the same data-wf-group value to link them into a navigable gallery. Arrow buttons, keyboard left/right, and touch swipe all move between items. A counter-pill (2 / 6) shows the current position.

Set data-wf-thumb on each trigger (or include an <img> inside it) to populate the thumbnail strip at the bottom of the lightbox.

HTML Copy

<a href="photo-1.jpg" data-wf-lightbox data-wf-group="album" data-wf-caption="Photo 1">
  <img src="thumb-1.jpg" alt="Photo 1">
</a>
<a href="photo-2.jpg" data-wf-lightbox data-wf-group="album" data-wf-caption="Photo 2">
  <img src="thumb-2.jpg" alt="Photo 2">
</a>
<a href="photo-3.jpg" data-wf-lightbox data-wf-group="album" data-wf-caption="Photo 3">
  <img src="thumb-3.jpg" alt="Photo 3">
</a>

<button data-wf-lightbox data-wf-group="demo-gallery"
        data-wf-src="photo-1.jpg"
        data-wf-thumb="thumb-1.jpg"
        data-wf-caption="First photo">Open</button>

Native Video

URLs ending in .mp4 , .webm , or .ogg are detected automatically as native video. The video element gets controls , autoplay , and playsinline . Set data-wf-type="video" explicitly if the URL has no recognizable extension (e.g., a signed CDN URL).

<!-- Auto-detected from .mp4 extension -->
<a href="demo.mp4" data-wf-lightbox data-wf-caption="Product demo">
  Watch demo
</a>

<!-- Forced type (signed CDN URL without extension) -->
<a href="https://cdn.example.com/video?token=xyz"
   data-wf-lightbox data-wf-type="video">
  Watch video
</a>

YouTube

YouTube URLs are auto-detected. Short ( youtu.be/ ), full ( youtube.com/watch?v= ), and embed ( youtube.com/embed/ ) formats all work. The video ID is extracted and the player is embedded via the YouTube iframe API with autoplay=1 .

<!-- Short URL -->
<a href="https://youtu.be/dQw4w9WgXcQ" data-wf-lightbox>Watch</a>

<!-- Full URL -->
<a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" data-wf-lightbox>Watch</a>

<!-- Embed URL -->
<a href="https://www.youtube.com/embed/dQw4w9WgXcQ" data-wf-lightbox>Watch</a>

Vimeo

Vimeo URLs ( vimeo.com/<id> or vimeo.com/video/<id> ) are auto-detected. The video ID is extracted and the player is embedded via the Vimeo iframe API with autoplay=1 .

<!-- Standard Vimeo URL -->
<a href="https://vimeo.com/123456789" data-wf-lightbox>Watch</a>

<!-- /video/ form also works -->
<a href="https://vimeo.com/video/123456789" data-wf-lightbox>Watch</a>

Iframe

Set data-wf-type="iframe" to load any URL in an embedded frame. The default frame is min(92vw, 1000px) wide and min(80dvh, 660px) tall. Override with data-wf-width and data-wf-height (values in px, no unit suffix needed).

<!-- Default iframe size -->
<a href="https://example.com/preview"
   data-wf-lightbox data-wf-type="iframe">
  Open preview
</a>

<!-- Custom dimensions (px, no unit) -->
<a href="https://example.com/map"
   data-wf-lightbox data-wf-type="iframe"
   data-wf-width="800" data-wf-height="500">
  View map
</a>

Play Button

Add the class wf-lightbox-play to a trigger wrapper to overlay a CSS-only play button on the thumbnail. Useful for video gallery cards where the thumbnail image should visually signal that clicking opens a video rather than a photo.

HTML Copy

<a href="https://youtu.be/dQw4w9WgXcQ"
   data-wf-lightbox class="wf-lightbox-play">
  <img src="video-thumb.jpg" alt="Watch video">
</a>

Data Attributes

All attributes go on the trigger element ( <a> , <button> , or any other element).

CSS Custom Properties

Declared on .wf-lightbox-overlay . Override on :root or any ancestor.

:root {
  --wf-lightbox-bg:         rgba(0, 0, 0, 0.92);
  --wf-lightbox-btn-size:   3rem;
  --wf-lightbox-radius:     0.75rem;
  --wf-lightbox-caption-bg: rgba(0, 0, 0, 0.65);
}

Programmatic API

The static WojoLightbox.open() and WojoLightbox.close() methods let you control the lightbox from JavaScript without any trigger element in the DOM.

import { WojoLightbox } from './wf-lightbox.js'

// Open a single image
WojoLightbox.open({
  src:     'photo.jpg',
  type:    'image',
  caption: 'My caption',
})

// Open a YouTube video
WojoLightbox.open({
  src:  'https://youtu.be/dQw4w9WgXcQ',
  type: 'youtube',
})

// Close from outside
WojoLightbox.close()

Events

Events are dispatched on the trigger element that opened the lightbox and bubble up the DOM. When opened via WojoLightbox.open() no trigger element is involved, so no events are fired.

document.addEventListener('wf:lightbox-open', e => {
  console.log('Opened:', e.detail.src, e.detail.type)
  console.log('Trigger element:', e.detail.trigger)
})

document.addEventListener('wf:lightbox-close', () => {
  console.log('Lightbox closed')
})

document.addEventListener('wf:lightbox-change', e => {
  console.log(`Gallery: ${e.detail.index + 1} of ${e.detail.total}`)
})

Class Reference

All overlay classes below are created and injected into <body> by the JS at open time and removed on close. The only class you add yourself is wf-lightbox-play on trigger wrappers.