Using the gallery features

This walkthrough turns a fresh install into a richer product gallery: hover zoom and the lightbox on every product, plus a featured video on the products that have one.

1. Enable zoom and the lightbox

Open the Reel menu and turn on Hover zoom and the Lightbox (both are on by default). They apply to every single product page that has a gallery, no per-product setup. Set the Zoom strength with the slider until the magnification suits your image sizes (1.0×-3.0×, default 1.45×), and if most of your traffic is mobile, leave Disable zoom on touch on so the zoom stays on desktop only. The lightbox and hover zoom are independent, running just one is fine.

2. Add a featured video to a product

First decide where the automatic video appears with the Position setting (after the gallery, or before the summary). Then on the product, set the _reel_video_url meta to your video:

• A self-hosted file ending .mp4, .m4v, .webm or .ogv plays in WordPress’s native video player.
• Anything else is treated as an oEmbed URL (YouTube, Vimeo and similar) and embedded automatically.

Optionally set _reel_video_title for a per-product heading; otherwise Reel uses the Default heading (and the Intro text) from settings, falling back to Product video if no heading is set anywhere.

The product page shows the video only when the product has a _reel_video_url and the Show featured video master switch is on. A product without a video URL renders nothing, there is no empty placeholder on the storefront.

3. Confirm on the product page

Open a product with a gallery and a video:

• Hover a gallery image, it magnifies within the frame.
• Click (or press Enter/Space) on an image, the lightbox opens full screen.
• The video appears in its 16:9 frame in the position you chose, with the Now playing eyebrow and heading above it (unless you turned the heading off).

Placing the video outside the gallery

To show the video somewhere other than the automatic gallery position, inside a tab, a long-form description, a custom layout, use the shortcode or block. Both render the same engine-built video the gallery position uses; this is a placement option, not a second feature.

[reel_video]

The shortcode takes two optional attributes:

[reel_video id="123" title="hide"]

• id, target a specific product by ID. Defaults to 0, which resolves to the current product (the post being viewed).
• title, "show" or "hide" to force the heading on or off for this placement. Omit it to follow the Show featured video heading setting.

The Reel: Featured video block (search “Reel” in the inserter, Media category) produces the same output and exposes the same two controls as block attributes (productId, showTitle). When the resolved product has no video, the block shows a short editor-only placeholder explaining how to set one, and renders nothing on the storefront. The shortcode and block reuse the gallery’s reserved-space frame, so there is no layout shift wherever you drop them.

Why a changed video may take a moment to appear

oEmbed URLs require a blocking remote request, so Reel caches the built video markup in a short-lived transient keyed by product ID, video URL and the autoplay setting. A successful build is cached for an hour; an empty result (for example a transient oEmbed failure) is cached for five minutes so it retries soon. Because the key includes the URL and autoplay flag, editing _reel_video_url or toggling autoplay invalidates the cache automatically, but a heading-only or position change is served from the cached markup until it expires.

Lightbox behaviour for keyboard and screen-reader users

The lightbox is fully keyboard operable:

• Open it with Enter or Space on a focused gallery image.
• Focus is held on the close control while it is open, so it can’t slip behind the overlay.
• Escape closes it; a backdrop click also closes it when Close on backdrop click is on. Focus returns to the image you opened it from.
• The dialog is named (role="dialog", aria-modal), and the open control uses your Open-image label, so assistive technology announces both clearly.
• With Image caption on, the image’s alt copy is shown as a caption.

Performance notes

Reel ships a single small vanilla-JavaScript file, deferred and loaded in the footer, only on the single product page, no jQuery, and no external request beyond the oEmbed fetch for embedded videos. The lightbox is a fixed overlay that starts hidden, the zoom transform is clipped to the gallery frame, and the video sits in a fixed-ratio frame that reserves its space before loading. Together that means Reel adds the gallery features with no Cumulative Layout Shift, and the styling respects prefers-reduced-motion.