How to add a gallery lightbox in WordPress

Since WordPress 6.4, released on November 7, 2023, the Image and Gallery blocks can open a clicked image in an overlay without any plugin. Many tutorials still say you need one. Whether you actually do depends on which gallery system the page uses. A WordPress site can have four of them, and each one’s settings leave the others alone.

So start by finding out what the page is really running. Then turn on the right setting. If the lightbox still misbehaves, work through the causes below in order.

Which gallery system is your page actually using?

Open the page in the editor and click the gallery. The block name or widget name tells you which system owns it. If you see a shortcode or a plugin’s own panel, it isn’t a core gallery.

What you find	What it is	Where the lightbox setting lives
A block named Gallery or Image	Core WordPress block	The block’s link options: Enlarge on click
in a Shortcode block or the Classic editor	Legacy shortcode gallery	None in core. You need a plugin that supports it
Images on a single product page	WooCommerce product gallery	The Product Gallery block, or your theme for classic product pages
A widget in Elementor, Kadence or a similar tool	Theme or page builder gallery	The widget’s own settings
A panel from FooGallery, NextGEN, Envira, Modula and so on	Gallery plugin	That plugin’s settings screen

To check what visitors get, right-click a gallery image on the live page and choose Inspect. Core galleries carry the class wp-block-gallery. Plugin and builder galleries usually include the plugin’s name in their class names.

How to turn on the built-in lightbox for a Gallery block

You need WordPress 6.4 or later and permission to edit the page. If you’re not sure which version you run, check your WordPress version first. On older versions the option doesn’t exist.

1. Open the page in the block editor and select the whole Gallery block, not one image inside it. If you keep landing on a single image, open List View and click the Gallery row.
2. Click the link icon in the block toolbar and choose Enlarge on click. Some sources call it Expand on click, so use whatever label your version shows.
3. For a single image, select the Image block, open Link and choose the same option.
4. Save or update the page.
5. Open the live page in a private window and click a thumbnail.

Here is what should happen. The image grows into an overlay on the same page, the URL stays the same, and a close button or the Escape key brings you back. If the image opens as a bare file in a new tab, the gallery is set to link to the media file. If you land on a page with one image on it, it’s linking to the attachment page.

Previous and next arrows depend on your version. WordPress.org’s current Gallery block documentation describes moving between images in the lightbox. Earlier versions opened each image on its own: in March 2025 a Reddit reply pointed out that Enlarge on click alone did not give you a sliding gallery. If you don’t see arrows, update WordPress before you install anything.

When a gallery plugin earns its place

Core handles click to enlarge. A dedicated plugin makes sense when you need things core doesn’t do:

• masonry, justified or filterable layouts;
• pagination for hundreds of images;
• video in the same gallery;
• albums;
• control over how captions look.

One small-business owner on Reddit with 350 tagged images is a fair example of a plugin-sized job. A portfolio with twelve photos isn’t.

A plugin also adds costs. It’s one more lightbox that can clash with core or your theme. Many advanced features sit in paid tiers. And it has to keep up with WordPress. After WordPress 6.7, WP Featherlight kept working on existing galleries, but the option to enable it on new ones disappeared. The site owner estimated that posting would now take two to three times as long.

If you do add one, read its setup notes for the link setting it expects. Many plugins need images to link to the media file and won’t fire on Enlarge on click or None. Turn the core lightbox off on any gallery the plugin handles. Our guide to installing a WordPress plugin safely covers how to add one without surprises.

WooCommerce product galleries follow their own rules

Changing a Gallery block in a post or page does nothing to your product pages. WooCommerce runs its own gallery, and the setting depends on your theme.

• Block themes: edit the Single Product template and select the Product Gallery block. WooCommerce’s documentation says it supports zoom, a full-screen pop-up and previous/next navigation. The pop-up is a block setting called Open pop-up when clicked.
• Classic themes: WooCommerce says the full-screen view behind the magnifying-glass icon depends on theme support. If your theme doesn’t declare it, you won’t get it. Changing that takes theme code or a theme with the support built in.

One more WooCommerce detail: the main Product Image already shows first in the gallery. If you add it again under Add product gallery images, it appears twice.

Why the lightbox does not open, opens twice or fails on mobile

Nobody publishes numbers on how often each cause turns up. Across support threads, though, the pattern is consistent: competing scripts come first, optimisation second, and settings and markup after that. Change one thing at a time and retest after each change.

Two lightboxes are handling the same click

The symptoms are an overlay inside an overlay, two sets of arrows, a close button you have to click twice, or a page that stops scrolling. This happens when a theme, a builder, core and a plugin all respond to the same click. The Responsive Lightbox documentation lists a theme’s own lightbox as a common cause of two lightboxes opening at once.

Turn one of them off. In one Reddit thread, a site owner ran Meow Lightbox alongside the core lightbox and tried to fix the clash with CSS and JavaScript. Images vanished and the page stopped scrolling. Hiding a lightbox with CSS doesn’t stop its script from running.

Script optimisation ran the lightbox too early

Open your browser’s developer tools and check the Console tab. If you see “jQuery is not defined”, a script is running before jQuery has loaded. Defer, delay, combine and minify settings in caching plugins often cause this.

In a July 2026 FooGallery support thread, turning off Autoptimize’s JavaScript optimisation fixed the gallery. Excluding foogallery.min.js from optimisation kept it working with optimisation back on. LiteSpeed documents the same approach:

1. Load the page with /?LSCWP_CTRL=before_optm to see it unoptimised.
2. Turn off CSS and JS optimisation and purge everything.
3. Test JavaScript and CSS separately.
4. Exclude one file at a time, purging between tests.

Don’t leave optimisation off for the whole site. A single exclusion fixes the gallery and costs far less speed.

The link setting is wrong for the lightbox you use

When the link setting is wrong, you get no error at all. The image does nothing, opens in a new tab or goes to an attachment page. Core needs Enlarge on click. Most plugins need Media file. Neither works with None.

The legacy shortcode is its own case. A WordPress.org support thread from 2026 confirms that isn’t supported. Convert the gallery to a Gallery block or use a plugin that supports the shortcode.

The lightbox cannot attach to the gallery’s markup

Many lightbox plugins only recognise standard WordPress gallery markup. Responsive Lightbox’s documentation says native galleries work but galleries built by themes or other plugins may not. Galleries that load images after the page loads, through AJAX or infinite scroll, cause the same problem. The lightbox scans the page once, before those images exist.

Look for a compatibility setting before you write code. Responsive Lightbox has an option to trigger ajaxComplete under Custom Events, and Jetpack galleries have a Force gallery lightbox option. “Each plugin works on its own” doesn’t tell you they work together.

A cache is still serving the old page

If your fix works while you’re logged in but visitors still see the broken version, a cache is serving them a stored copy. Purge the caching plugin, then the host’s server cache, then the CDN, and retest in a private window. Kinsta’s documentation says clearing the server cache doesn’t clear the CDN, which can keep old JavaScript, CSS and images.

It fails only on phones

Test on the device that fails, not a resized desktop browser. Mobile failures tend to be specific to one setup:

• A NextGEN and Enfold site showed “Gallery could not load” on iOS until a CSS height fix for that theme.
• A FooGallery page with more than 240 images crashed on iPhone. Support suggested setting the lightbox scroll bar option to Default, using two columns on mobile and adding pagination.

Very long galleries are the common thread. Split or paginate them.

Isolate it when none of the above is obvious

The Health Check plugin’s troubleshooting mode disables plugins and switches to a default theme for your logged-in session only. Visitors see nothing change. Turn plugins back on one at a time until the lightbox breaks. Our guide to fixing plugins that stop working walks through the same method in more detail.

Stop and get help when the Console shows an error inside the gallery plugin’s own file, when the gallery works in the editor but not on the live page, or when the fix means editing PHP. Send the plugin’s support forum your plugin and theme names and versions, your WordPress and PHP versions, and the full error text. If you’d rather not trace it yourself, SiteSelf can find and fix the broken feature on your live site and report what it changed. Script exclusions and code changes need hosting access.

Check keyboard and search behaviour before you call it done

A lightbox is a modal dialog, and the W3C’s ARIA Authoring Practices Guide describes how one should behave:

• Focus moves into the overlay when it opens.
• Tab and Shift+Tab stay inside it.
• Escape closes it.
• Focus goes back to the thumbnail that opened it.
• The page behind can’t be used while it’s open.
• A visible close button is part of the same pattern.

Test it with only the keyboard. Many lightboxes look fine and still trap keyboard users.

Give every gallery image real alt text. Use alt="" only for images that are purely decorative. For search, Google’s lazy-loading guidance says content has to load when it becomes visible, without anyone clicking. A lightbox that shows a larger version is fine, as long as the thumbnail is a real image on the page and not something only a click reveals.