Lightbox with PhotoSwipe

The plugin uses JavaScript modules for PhotoSwipe 5. This will not work, if you use any kind of “JavaScript optimizing” with a WordPress plugin which combines all frontend scripts into one single file. Make sure that Lightbox with PhotoSwipe is excluded from any kind of “optimization”, otherwise the plugin may not work.

All linked images in a post or page will be displayed using PhotoSwipe, regardless if they are part of a gallery or single images.

Make sure that you link the image or gallery directly to the media and not the attachment page (in galleries the option link=file should be set).

If you want to display an image in it’s own lightbox which does not display other images from the same post or page, you can add the attribute data-lbwps-gid to the link element with a unique value for this image. This value must not be a number since numbers are already used internally. For example you could the file name of the image like this:

<a href="myimage.jpg" data-lbwps-gid="myimage.jpg"><img src="myimage-300x300.jpg" alt="My Image" /></a>

You can also add the same data-lbwps-gid attribute to multiple single images to combine them in the same lightbox.

Note: the parameter was renamed from data-gallery-id to data-lbwps-gid in version 2.97 to avoid conflicts with existing themes or plugins!

Starting with release 3.1.14 this is also supported for Elementor image widgets and Elementor image carousel widgets.

Please note: the order of the parameters have changed in version 1.90.

Some other plugins use PhotoSwipe as well and it may be neccessary to disable Lightbox with PhotoSwipe on some pages or posts – for example on the product pages of WooCommerce.

You can either configure the pages/posts manually in the settings or you can use the filter lbwps_enabled. This filter gets the ID of the current page/post and if the lightbox is currently enabled (true or false). If the filter returns true, the lightbox will be used, if it returns false the lightbox will be disabled – which means, no scripts and stylesheets will be included at all on the current page/post.

Example:

// Disable Lightbox with PhotoSwipe on WooCommerce product pages

function my_lbwps_enabled($enabled, $id)
{
    if (function_exists('is_product')) {
        if (is_product()) return false;
    }

    return $enabled;
}

add_filter('lbwps_enabled', 'my_lbwps_enabled', 10, 2);

The individual parts of the caption can be modified using the following filters. Each filter gets the ID of the current page/post and the original text to be used. You can either return the text as it is or modify it if needed.

lbwps_caption_caption
lbwps_caption_title
lbwps_caption_description
lbwps_caption_filename
lbwps_caption_exif

Example:

// Add copyright notice to caption title

function my_lbwps_caption_title($title, $id)
{
    return sprintf('%s<br>Copyright (c) %s Foobar', $title, date('Y'));
}

add_filter('lbwps_caption_title', 'my_lbwps_caption_title', 10, 2);

PhotoSwipe 5 improves the overall performance and compatibility with newer mobile devices like the iPhone 13. However, some features are no longer supported by that version:

1) Customizing the display of image counter and zoom button (this may be added in future updates).

2) All mobile specific options (some options may return in future updates).

3) Sharing options (some options may return in future updates).

Which styles are available depends on which PhotoSwipe version you use and what kind of caption.

Please use the web developer tools of your browser to examine the caption elements and to learn which CSS classes
are used.

PhotoSwipe has the option to create a zoom animation from the thumbnail to the final image when opening the lightbox. However, this does not work well with square thumbnails since the thumbnail is just enlarged to the final image size without keeping its aspect ratio. This would result in a quite weird image display where a square thumbnail gets stretched to a portrait or landscape image before the final image is loaded. Just having a fade-in animation is the better solution.

Lightbox with PhotoSwipe works fine with Gutenberg gallery blocks as well. However when you use the “PublishPress Blocks” plugin it brings its own lightbox script which can cause conflicts. To avoid any problems, you should disable the Advanced Gutenberg lightbox in the settings. Disable the option “Open galleries in lightbox” in the backend configuration of PublishPress Blocks.

If you want to display the images not in the order in which they are in the source code you can use the attribute tabindex in the image links. Also see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex on how to use this attribute.

SVG is a vector based format and SVG images can be displayed at any size. However PhotoSwipe needs to know the size of an image to be able to display it in the lightbox.

Lightbox with PhotoSwipe tries to determine the size based on the width/height attribute of the root element in the SVG structure. If these attributes are not available, the viewbox is used. If none of these values are present, the SVG can not be displayed in the lightbox.

Reading SVG files also requires the SimpleXML extension for PHP to be available. Without this extension SVG files can not be displayed at all.

To avoid any confusion: this plugin was published with the agreement of Dmytro Semenov.

If you change any of the stylesheets or frontend scripts in src/js or src/lib you need to run make build to generate new compressed frontend assets.

The main repository for the source code can be found at https://codeberg.org/askaaron/lightbox-photoswipe.