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: No nonce required. The request must name the item’s Gallery as gallery_id, and it follows that Gallery’s password and access settings.

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": {
        "name": "Eastern Ridge",
        "latitude": 45.123,
        "longitude": -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.

latitude and longitude are included only when the Gallery’s info panel shows the Location block. exif contains only the fields set in the Gallery’s EXIF Fields setting, and is null when the EXIF block is off.

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