Ecom Dynamic Gallery

Self-contained WordPress module that renders a photo gallery: a main image plus a horizontal-scrolling thumbnail row, a custom scrollbar with arrows, mouse drag-to-scroll on desktop, and swipe gestures on mobile. Single shortcode, no DB, no admin UI. Vanilla JS, no jQuery.

Public surface: [ecom_gallery].

Distributed under the MIT License.

Features

• Main image + horizontal thumbnail row (capped at 16 images).
• Click a thumbnail → main image fades, swaps, fades back in.
• Full-screen lightbox viewer — click (or Enter/Space on) the main image to open. Prev/next buttons, ←/→/Home/End keys, ESC to close, click-backdrop to close, focus trap, body scroll lock, touch swipe, and an image counter ("3 / 12").
• Responsive image sources — every <img> ships with srcset and sizes, so mobile clients download a right-sized variant instead of the full large source.
• Intrinsic width/height on every <img> — eliminates Cumulative Layout Shift on first paint.
• Keyboard navigation across thumbnails — roving tabindex (one tab stop), ←/→ move between thumbs, Home/End jump to first/last, Enter/Space activate.
• Custom scrollbar under the thumbnails with prev/next arrows, a draggable thumb, and click-to-page behavior.
• Mouse drag-to-scroll on the thumbnail row (desktop / pen).
• Touch swipe on the main image (mobile / pen) → previous / next.
• Lazy-loaded thumbnails; main image marked fetchpriority="high".
• ARIA live region announces the new image's alt text on swap.
• Honors prefers-reduced-motion (no fade, no smooth scroll, no lightbox open/close transition).
• Two render modes: ACF-driven (default) or explicit attachment IDs (any page).

Installation

Option 1 — As a (child) theme module

Clone or copy the folder into your theme:

cd wp-content/themes/<your-theme>
git clone https://github.com/josipmestrovic/ecom-dynamic-gallery.git dynamic-gallery

Then add this line to your theme's functions.php:

require_once get_stylesheet_directory() . '/dynamic-gallery/dynamic-gallery.php';

Option 2 — As a must-use plugin

Copy the folder into wp-content/mu-plugins/dynamic-gallery/, then add a one-line loader at wp-content/mu-plugins/load-dynamic-gallery.php:

<?php
require_once WPMU_PLUGIN_DIR . '/dynamic-gallery/dynamic-gallery.php';

Option 3 — Composer

composer require josipmestrovic/ecom-dynamic-gallery

No DB, no admin UI, no AJAX, no options.

Usage

ACF mode (default)

[ecom_gallery]
[ecom_gallery post_id="42"]

Without post_id, the shortcode resolves the current post — including Divi Theme Builder templates, where it falls back to get_queried_object_id() so the gallery shows images from the post being viewed (not from the template post).

Reusable mode — any page (About Us, landing pages, etc.)

Pass a comma-separated list of attachment IDs. ACF is not consulted and post_id is ignored:

[ecom_gallery images="123,124,125,126"]
[ecom_gallery images="123,124,125,126" featured="125"]

Get the attachment ID from the Media Library (URL bar: ?item=123 or the File URL field in the attachment details panel).

Rendered markup

Skeleton of what the shortcode prints. Class names and ARIA attributes are stable hooks — themers can rely on them.

<div class="tg-gallery">
    <div class="tg-main-image"
         role="region"
         aria-roledescription="Image gallery main view"
         aria-live="polite"
         aria-atomic="true">
        <!-- JS upgrades this wrapper to role="button" tabindex="0" so
             it opens the lightbox via click / Enter / Space. -->
        <img id="tg-main-img"
             src="…"
             srcset="… 480w, … 1024w"
             sizes="(max-width: 800px) 100vw, 800px"
             width="1024" height="683"
             alt="…" fetchpriority="high">
    </div>

    <div class="tg-thumbnails">
        <button class="tg-thumb tg-thumb--active"
                type="button"
                tabindex="0"
                aria-pressed="true"
                aria-label="…"
                data-large="…"
                data-large-srcset="…"
                data-large-sizes="…"
                data-large-w="1024" data-large-h="683"
                data-full="…"
                data-alt="…">
            <img src="…"
                 srcset="…" sizes="(max-width: 767px) 90px, 120px"
                 width="300" height="200"
                 alt="…" loading="lazy" decoding="async">
        </button>
        <!-- … more .tg-thumb buttons (tabindex="-1" until activated) … -->
    </div>

    <div class="tg-scrollbar" aria-hidden="true">
        <button class="tg-scrollbar__arrow tg-scrollbar__arrow--prev …">…</button>
        <div class="tg-scrollbar__track">
            <div class="tg-scrollbar__thumb"></div>
        </div>
        <button class="tg-scrollbar__arrow tg-scrollbar__arrow--next">…</button>
    </div>
</div>

The thumbnail row + scrollbar are only rendered when there is more than one image to show.

Behavior

Accessibility

Implemented:

• Active thumbnail exposes aria-pressed="true|false" (in addition to the .tg-thumb--active class).
• Roving tabindex on the thumbnail row. Only the active thumb has tabindex="0"; the rest are tabindex="-1". ←/→ move focus + activate, Home/End jump to first/last, Enter/Space activate. Tab leaves the row in a single hop.
• Lightbox dialog. role="dialog" + aria-modal="true", focus is trapped inside while open, focus moves to the close button on open, and is restored to the triggering element on close. Esc closes. Body scroll is locked (overflow: hidden) while open. Counter is a polite live region.
• The main image wrapper is keyboard-activatable (tabindex="0" role="button") so non-mouse users can open the lightbox with Enter/Space.
• .tg-main-image is a polite live region with aria-roledescription="Image gallery main view"; the <img> alt is updated on swap, so screen readers announce the new image.
• Alt-text input is escaped with esc_attr() everywhere it lands in an HTML attribute.
• prefers-reduced-motion: reduce disables the fade transition on the main image, the lightbox open/close transition, and forces behavior: 'auto' for scrollIntoView and the custom-scrollbar paging.
• Focus-visible outline on .tg-thumb and .tg-main-image uses the brand color #1C4168; lightbox controls use a white outline.
• Custom scrollbar arrows are aria-hidden="true" and tabindex="-1" so they don't add noise to the tab order or the screen-reader tree.

Not implemented (intentional, may be added later):

• No keyboard-exposed scrollbar arrows / role="scrollbar" ARIA on the custom track (A1's roving tabindex already gives keyboard users a way to traverse the gallery).

Performance

• Each thumbnail <img> is rendered with loading="lazy" and decoding="async". Off-screen thumbs are not requested until the row scrolls them near the viewport.
• The main <img> is rendered with fetchpriority="high" so it is prioritized as a likely LCP candidate.
• Responsive sources. Every <img> ships with srcset (built via wp_get_attachment_image_srcset) and a sizes hint that matches the responsive CSS — (max-width: 800px) 100vw, 800px for the main image, (max-width: 767px) 90px, 120px for thumbnails. Mobile and low-DPR clients download a smaller variant instead of the full large source.
• Intrinsic dimensions. Every <img> carries width and height attributes from wp_get_attachment_image_src, so the browser can reserve aspect-ratio space and Cumulative Layout Shift stays at zero on first paint. Dimensions are also re-applied on swap.
• Galleries are capped at 16 images in both ACF mode and reusable mode (array_slice( …, 0, 16 ) in includes/helpers.php).
• The custom scrollbar updates on the native scroll event (passive listener) — no requestAnimationFrame loop is running while idle.
• The lightbox markup is built lazily on first open and reused for subsequent opens; the per-gallery overhead is one DOM node.

Responsive behavior

The main image radius softens to 12px on mobile.

ACF fields consumed

(ACF mode only.)

Alt text is read from each attachment's WordPress alt field and escaped before being placed in HTML attributes.

File structure

dynamic-gallery/
├── README.md                    ← you are here
├── LICENSE                      ← MIT
├── composer.json
├── dynamic-gallery.php          ← thin bootstrap, requires every includes/*.php
├── dynamic-gallery.css          ← gallery styles
├── dynamic-gallery.js           ← swap logic, custom scrollbar, drag, swipe, lightbox
└── includes/
    ├── assets.php               ← register CSS/JS with filemtime cache-buster
    ├── helpers.php              ← post-id resolver + image collectors (ACF + IDs)
    └── shortcode-gallery.php    ← [ecom_gallery] render callback

Public surface

Public PHP functions

CSS class hooks

Styling tokens

Quick reference for the values currently hard-coded in dynamic-gallery.css. Edit there to retheme.

How to extend

Constraints

• One gallery per page. The main <img> uses a hard-coded id="tg-main-img"; rendering two instances on the same page will collide. Multi-instance support would require switching to a scoped class lookup.
• ACF dependency. ACF mode requires the Advanced Custom Fields plugin and the featured_image / gallery field definitions. Reusable mode (with images="…") does not.
• Pointer Events required. The drag, swipe, and custom-scrollbar thumb drag all use the Pointer Events API. All evergreen browsers support it; legacy browsers will fall back to native scroll only.
• Mouse-click on the main image opens the lightbox. Clicks (no drag) and Enter/Space on the focused main image both open the full-screen viewer; touch/pen swipes still cycle the active image.

Browser support

Targets evergreen Chrome, Firefox, Edge, and Safari ≥ 15.4. Required APIs: Pointer Events, CSS aspect-ratio, CSS scroll-behavior, Element.scrollBy({ behavior }), requestAnimationFrame, and MediaQueryList (for prefers-reduced-motion).