Ultimate Product Gallery

Ultimate Product Gallery for WooCommerce upgrades the standard WooCommerce product gallery so shoppers can browse images, watch video, and open PDFs, all from one place. It is designed to work across classic themes, block themes (Site Editor), and popular page builders, while keeping your core WooCommerce product images in sync for compatibility.

Key capabilities:

• Mixed media galleries: images, self-hosted video, YouTube, Vimeo, and PDFs.
• Store-wide defaults plus template-level and per-product overrides.
• Automatic use of existing WooCommerce featured + gallery images (no rebuilding required).
• Sync back to core WooCommerce image fields when you manage images in Ultimate Product Gallery.

If you run into a theme edge case or need a workflow that is not covered yet, contact support with details (and the debug output if available). Feature requests are welcome.

Requirements

↑ Back to top

• WordPress 6.5+
• WooCommerce 8.0+
• PHP 8.1+

Setup and configuration

↑ Back to top

Store-wide defaults

↑ Back to top

Store-wide defaults control the baseline gallery behavior for your catalog.

1. Go to: “WooCommerce > Settings > Product Gallery”.
2. Configure your “Default Gallery Settings”, such as:
   • Gallery layout (Grid or Scroller)
   • Thumbnail position (Top, Bottom, Left, Right)
   • Thumbnail size and aspect ratio
   • Thumbnail hover behavior (Preview / Commit / None)
   • Zoom and lightbox options
   • Video autoplay default
   • Optional thumbnail button colors
3. Click “Save changes”.

Notes:

• These settings define your global defaults.
• Some contexts (block templates, Elementor, Divi) can override defaults at the template level. Per-product overrides always take priority.

Add and manage gallery items per product

↑ Back to top

1. Go to: “Products > All Products”.
2. Edit a product.
3. Locate the “Ultimate Product Gallery” panel.
4. Add gallery items using any of the following:
   • “Add from media library” (images, videos, PDFs)
   • “Add remote media” (paste a URL to an image, video, YouTube/Vimeo link, or PDF)
   • Drag and drop files into the preview area to upload quickly
5. Reorder items:
   • Drag thumbnails in the preview, or
   • Use “Move left” / “Move right” in the sidebar controls (if available)
6. Click “Update” to save the product.

Per-item fields you can edit:

• Item type: Image, Video, PDF
• Source URL: Direct media URL or embed URL
• Alt text and caption
• Visibility: Hide an item without deleting it
• Thumbnail: Select from the media library or paste a URL
• Video options (available depending on provider):
  • Self-hosted video poster (select an image, paste a URL, or capture a frame)
  • Playback controls, autoplay (muted), muted, loop
  • YouTube options (related videos, modest branding, start/end, playlist, captions, etc.)
  • Vimeo options (DNT, background mode, quality, color, text track, etc.)

Existing WooCommerce images and automatic sync

↑ Back to top

You do not need to rebuild your product galleries after installing the plugin.

• If a product already has a featured image and gallery images set in WooCommerce, Ultimate Product Gallery will use those images automatically.
• When you add or reorder images in Ultimate Product Gallery, it keeps the WooCommerce featured image and product gallery images in sync for compatibility with themes and plugins that rely on core WooCommerce image data.
• Videos and PDFs are stored only in Ultimate Product Gallery (WooCommerce core galleries are image-only).

Common tasks

↑ Back to top

Add a YouTube or Vimeo product video:

1. Edit a product.
2. In the “Ultimate Product Gallery” panel, click “Add remote media”.
3. Set “Media type” to “Video”.
4. Set “Video provider” to YouTube or Vimeo (or leave it set to auto-detect).
5. Paste the video URL and click “Add media”.
6. Select the new item in the preview to adjust playback controls, autoplay, captions, or provider-specific options.
7. Click “Update”.

Add a PDF (size chart, manual, spec sheet):

1. Edit a product.
2. In the “Ultimate Product Gallery” panel, click “Add from media library”.
3. Select a PDF (or upload one).
4. Set the item’s alt text to something meaningful (example: “Download size chart”).
5. Click “Update”.

Hide an item without deleting it:

1. Select the item in the preview.
2. Toggle “Visible in gallery” off.
3. Click “Update”.

Settings hierarchy

↑ Back to top

Ultimate Product Gallery resolves settings in this order (highest priority first):

1. Per-product settings in the product editor.
2. Page builder / template settings (Block editor, Elementor, Divi), if present.
3. Global defaults in “WooCommerce > Settings > Product Gallery”.

Where supported, the product editor indicates when a setting is inheriting and what it is inheriting from.

Theme and builder integration

↑ Back to top

Classic themes

↑ Back to top

For classic themes that use the standard WooCommerce single product gallery output, Ultimate Product Gallery replaces the frontend output automatically.

Block themes and the Site Editor

↑ Back to top

If you are using a block theme:

• If your product template includes the WooCommerce “Product Image Gallery” block, Ultimate Product Gallery will replace the frontend output automatically.
• If you want template-level overrides (for example, different layouts per template), insert the “Ultimate Product Gallery” block and configure its settings. Leave controls set to “Inherit” to use your global defaults.

Tip: In the Site Editor, the block may provide a “Product ID override” (when available) to preview the gallery with a specific product while designing a template.

Elementor

↑ Back to top

If you build product templates with Elementor:

1. Open your single product template in Elementor Theme Builder.
2. Insert the “Ultimate Product Gallery” widget.
3. Adjust widget settings, or leave them set to “Inherit” to use global defaults.
4. Update the template.

Divi

↑ Back to top

If you build product templates with Divi:

1. Edit the product template with the Divi Builder.
2. Insert the “Ultimate Product Gallery” module.
3. Adjust module settings, or leave them set to “Inherit” to use global defaults.
4. Save.

Shortcode

↑ Back to top

Use the shortcode to render a product gallery in any shortcode-enabled area.

Render the current product (when used on a product page):

[upg_gallery]

Render a specific product gallery:

[upg_gallery product_id="123"]

Tools

↑ Back to top

At the bottom of “WooCommerce > Settings > Product Gallery”, optional tools may be available:

• “Create demo products”: Generates demo products showcasing mixed media galleries (images, self-hosted video, YouTube, Vimeo, PDFs, and hidden items). Useful for quickly testing settings.
• “Remove plugin data”: Deletes saved defaults, per-product overrides, and gallery data from the database. Media files are not removed. This action cannot be undone.

Frontend behavior

↑ Back to top

What customers see on the product page:

• A main media area with a thumbnail strip (position depends on your settings).
• Clicking a thumbnail switches the main media.
• Optional hover behaviors:
  • Preview on hover: hovering previews without changing the selected item.
  • Commit on hover: hovering changes the selected item.
  • No hover: only clicking changes the selected item.
• Images:
  • Optional hover zoom
  • Optional lightbox (full-screen viewing)
• Videos:
  • Self-hosted video uses the native HTML5 video player.
  • YouTube/Vimeo embeds load their respective players.
• PDFs:
  • An embedded PDF viewer when supported by the browser
  • A fallback download link if embedding is not supported or blocked

Troubleshooting

↑ Back to top

The gallery does not appear on the product page

↑ Back to top

1. Confirm WooCommerce is active and Ultimate Product Gallery is activated.
2. Confirm the product has at least one gallery item (or at least one core WooCommerce product image).
3. Check your theme/builder setup:
   • Classic theme: the gallery output is replaced automatically.
   • Block theme: ensure the product template includes a product gallery block.
   • Elementor/Divi: ensure you inserted the Ultimate Product Gallery widget/module in the template.
4. Clear page cache and any asset optimization cache.

If it still does not render, enable the debug bar (below) and contact support with a screenshot of the debug output.

YouTube/Vimeo poster image is missing

↑ Back to top

Some hosts or firewalls block outbound requests required to fetch thumbnails from video providers.

Fix:

• Set a thumbnail manually on the item (the “Thumbnail” field), or
• Set a poster image in the “Video poster” section.

Autoplay does not work

↑ Back to top

Most browsers only allow autoplay when the video is muted.

Fix:

• Enable autoplay and keep muted enabled.
• Note: Some mobile browsers may still require user interaction before playback.

PDF does not embed

↑ Back to top

Common causes:

• The browser does not support embedded PDFs.
• The remote host blocks embedding via security headers.

Fix:

• Upload the PDF to your media library (self-host), or
• Rely on the built-in download fallback link.

Clicking thumbnails does nothing, or zoom/lightbox does not work

↑ Back to top

This is usually caused by a JavaScript conflict or an optimization plugin deferring/minifying scripts too aggressively.

1. Temporarily disable your JS/CSS optimization plugin and re-test.
2. If that resolves the issue, exclude Ultimate Product Gallery assets from optimization:
   • Script handle: upg-frontend
   • Style handle: upg-styles
3. Check the browser console for errors and include them in your support request.

Debugging: see which settings are applied

↑ Back to top

1. Go to: “WooCommerce > Settings > Product Gallery”.
2. Enable “Enable gallery debug bar” and save changes.
3. View a product page while logged in as an admin or shop manager.
4. In the WordPress admin bar, open “Gallery Debug” to review:
   • Global defaults
   • Builder/template overrides (if any)
   • Per-product overrides (if any)
   • Final resolved settings

FAQs

↑ Back to top

Does it require WooCommerce?

↑ Back to top

Yes. Ultimate Product Gallery requires WooCommerce to be installed and active.

What media types can I add?

↑ Back to top

• Images
• Videos (self-hosted, YouTube, Vimeo)
• PDFs

Does it connect to external services?

↑ Back to top

Only when you add external media URLs, such as YouTube or Vimeo videos.

Depending on the media you add, the plugin may make outbound requests to:

• Detect media type and resolve metadata (for example, size or format).
• Resolve provider thumbnails when available.

On the frontend, visitors may load YouTube or Vimeo players when they view embedded videos.

Can I hide an item without deleting it?

↑ Back to top

Yes. Each gallery item includes a “Visible in gallery” toggle. Hidden items are not displayed to customers, but remain saved for later use.

How do I show the gallery somewhere else?

↑ Back to top

Use the Ultimate Product Gallery block/widget/module (template/builder contexts) or the [upg_gallery] shortcode.

Support

↑ Back to top

If you purchased through WooCommerce.com, open a support request from your WooCommerce.com account.

When contacting support, include:

• A link to a product page that shows the issue (or a staging URL).
• Your theme name and any builder in use (Site Editor / block theme, Elementor, Divi, etc.).
• The media types involved (images, YouTube, Vimeo, PDFs, self-hosted video).
• A screenshot of the “Gallery Debug” panel (recommended).
• Any relevant browser console errors (if the issue appears to be JavaScript-related).