Lightbox: Developer Reference

Technical reference for developers working with the FotoGrids Lightbox — custom events, HTML trigger attributes, the data-fg-lb-* settings system, and the REST endpoint the info panel uses.

Audience: Developers building custom themes, rendering galleries outside WordPress, or extending Lightbox behavior with JavaScript.

Custom Events #

The Lightbox dispatches three custom events on the gallery wrapper element (the .fotogrids-gallery element that wraps the items). Listen at the gallery level to scope handlers to a specific gallery. Events also bubble, so document-level listeners work.

fotogrids:lightbox:open

Fired when the Lightbox opens on an item.

galleryEl.addEventListener( 'fotogrids:lightbox:open', ( e ) => {
    const { galleryEl, index, item } = e.detail;
} );

fotogrids:lightbox:navigate

Fired each time the visitor moves to a different item — by arrow, dot, keyboard, swipe, or thumbnail click.

galleryEl.addEventListener( 'fotogrids:lightbox:navigate', ( e ) => {
    const { galleryEl, index, item, direction } = e.detail;
} );

fotogrids:lightbox:close

Fired when the Lightbox closes, before focus is returned to the trigger element.

galleryEl.addEventListener( 'fotogrids:lightbox:close', ( e ) => {
    const { galleryEl } = e.detail;
} );

Item Object

The item object passed in open and navigate events:

{
    triggerEl,   // Element  — the <a> with [data-fg-lightbox-trigger] that was clicked
    fullSrc,     // string   — URL of the full-size image/video (href of the trigger)
    thumbSrc,    // string   — URL of the thumbnail (src of the <img> inside the trigger)
    alt,         // string   — alt text of the thumbnail image
    caption,     // string   — value of data-fg-caption on the trigger
    title,       // string   — value of data-fg-title on the trigger
    id,          // string   — value of data-fg-item-id on the trigger (used for REST fetch)
}

HTML Trigger Attributes #

The Lightbox is initialised entirely from the DOM — no JavaScript configuration object is required.

On the gallery wrapper element

On each item’s <a> link

A minimal hand-authored gallery structure:

<div class="fotogrids-gallery" data-fg-click="lightbox" data-fg-lb-theme="dark">

    <figure>
        <a href="https://example.com/photo-full.jpg"
           data-fg-lightbox-trigger
           data-fg-item-id="42"
           data-fg-caption="Sunrise over the valley">
            <img src="https://example.com/photo-thumb.jpg" alt="Sunrise over the valley">
        </a>
    </figure>

    <figure>
        <a href="https://example.com/photo2-full.jpg"
           data-fg-lightbox-trigger
           data-fg-item-id="43"
           data-fg-caption="Golden hour">
            <img src="https://example.com/photo2-thumb.jpg" alt="Golden hour">
        </a>
    </figure>

</div>

The data-fg-lb-* Settings System #

All Lightbox settings are read from data-fg-lb-* attributes on the gallery wrapper at open time. The PHP renderer writes these from the gallery’s stored settings — but they can be set or overridden directly in HTML.

Boolean attributes: Present means enabled, absent means disabled — no value is needed (e.g. data-fg-lb-fit-media with no ="true"). The naming convention flips for no- prefixed attributes: data-fg-lb-no-loop present means loop is disabled.

Theme & Colors

Layout & Behavior

Navigation & Transition

Auto-Progress

Thumbnail Strip

Zoom

Info Panel

Info block IDs (for data-fg-lb-info-blocks):
caption description file_info exif share credit tags people location rating download

EXIF field keys (for data-fg-lb-exif-fields):
camera aperture shutter_speed iso lens focal_length date_taken copyright orientation flash white_balance exposure_mode

Image Filters

Example: data-fg-lb-full-filter="grayscale(100%)" renders all items in black and white until hovered.

Info Panel REST Endpoint #

When a visitor opens an item, the Lightbox fetches extended metadata from:

GET /wp-json/fotogrids/v1/lightbox/item/{id}

Authentication: Public — no nonce or authentication required.

Path parameter:

Response shape:

{
    "id": 42,
    "caption": "Sunrise over the valley",
    "description": "Taken at 5:43am on the eastern ridge.",
    "credit": "© Jane Smith",
    "file_info": {
        "filename": "sunrise.jpg",
        "filesize": "2.4 MB",
        "width": 4000,
        "height": 2667,
        "mime_type": "image/jpeg"
    },
    "exif": {
        "camera": "Canon EOS R5",
        "aperture": "f/2.8",
        "shutter_speed": "1/250s",
        "iso": "400",
        "lens": "RF 85mm f/1.2L",
        "focal_length": "85mm",
        "date_taken": "2025-01-12 05:43:00",
        "copyright": "© Jane Smith",
        "orientation": "Landscape",
        "flash": "No Flash",
        "white_balance": "Auto",
        "exposure_mode": "Manual"
    },
    "tags": [
        { "id": 7, "name": "Landscape", "slug": "landscape" }
    ],
    "people": [
        { "id": 3, "name": "Jane Smith", "slug": "jane-smith" }
    ],
    "location": {
        "id": 5,
        "name": "Eastern Ridge",
        "slug": "eastern-ridge",
        "lat": 45.123,
        "lng": -122.456
    }
}

Fields not set for an item are returned as null (scalars) or [] (arrays). The Lightbox silently skips rendering any block whose data is null or empty.

Caching: Responses are cached in memory for the page session. Navigating back to a previously opened item shows cached data immediately without a second request.

The Lightbox Singleton #

The Lightbox is a singleton — one FotoGridsLightbox instance is created at page load and reused across all galleries on the page. It is accessible at:

window._fgLightbox   // internal reference — treat as read-only