Lightbox with PhotoSwipe


This plugin integrates an extended version of PhotoSwipe 4 or the official release of PhotoSwipe 5 to WordPress. All linked images in a post or page will be displayed using PhotoSwipe, regardless if they are part of a gallery or single images. Just 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).

More about the original version of PhotoSwipe see here:

The version of PhotoSwipe 4 provided with this plugin comes with a number of modifications and extensions. See the FAQ for details.

As of version 4.0.0 this plugin requires at least WordPress 5.3 and PHP 7.0. Older PHP version will cause problems. In this case you have to upgrade your PHP version or ask your hoster to do so. Please note that WordPress itself also recommends at least PHP 7.4 – see


  • General options in the backend
  • Theme options in the backend
  • Options for captions in the backend
  • Sharing options in the backend
  • Desktop options in the backend
  • Mobile options in the backend


  1. Extract the contents of the package to the /wp-content/plugins/lightbox-photoswipe directory
  2. Activate the plugin through the ‘Plugins’ menu in WordPress


Using the plugin

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.

The plugin seems not to work properly

Some themes or plugins have their own lightbox implementation which can cause a conflict with Lightbox with PhotoSwipe. In this case you need to disable the lightbox of the theme or other plugins if possible.

Also keep in mind that linked images which are added using JavaScript after the page has been loaded already by the browser will not be displayed with Lightbox with PhotoSwipe if they are missing the attributes data-lbwps-width and data-lbwps-height with the width and height of the image.

How to disable the plugin in certain pages/posts

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.


// 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);

How to modify the caption

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.



// 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);

How to modify the PhotoSwipe markup

Note: this only applies for PhotoSwipe 4! Starting with PhotoSwipe 5 modifying the markup is not supported any longer, since there is no static markup included.

If you want to modify the existing PhotoSwipe 4 markup, you can use the filter lbwps_markup. This filter gets one parameter with the existing markup and must return the modified markup to be used.

A «quick & dirty» example to add additional stuff in the header with the controls (CSS should never be inline – this is just to get a working example):

function my_lbwps_markup($markup)
    // Add some additional elements
    $markup = str_replace(
        '<div class="pswp__top-bar">',
        '<div class="pswp__top-bar"><div style="position:absolute; width:100%; text-align:center; line-height:44px; font-size:13px; color:#fff; opacity: 0.75;">Our content</div>',
    return $markup;

add_filter('lbwps_markup', 'my_lbwps_markup', 10, 1);

Changes with PhotoSwipe 5

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) Updating the browser history when opening the lightbox or navigating through images (this is no longer supported by PhotoSwipe).

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

3) All desktop and mobile specific options (some options may return in future updates).

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

How to style the caption

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.

Why is there no «zoom animation» when opening the lightbox?

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.

Conflict with PublishPress Blocks (Advanced Gutenberg Blocks)

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.

How to use the PhotoSwipe API?

Note: this only applies for PhotoSwipe 4! Starting with PhotoSwipe 5 there is no API hook yet!

The PhotoSwipe instance for the gallery is available as window.lbwpsPhotoSwipe after the gallery was initialized. Please note, that this variable is null if the lightbox is not open! This can be used to build your own extensions using the PhotoSwipe API. Also see how to use the API.

How to change the order of the images in the lightbox?

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 on how to use this attribute.

Why are my SVG images not displayed properly in the lightbox or not displayed at all?

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.

Local changes in PhotoSwipe

Note: this only applies for PhotoSwipe 4! PhotoSwipe 5 is used without any changes.

The following changes are the differences to PhotoSwipe 4.0 as of 2020-04-14:

1) The default UI is based on a CSS file and a number of graphics in different formats. This CSS file got modified to provide a fix for WordPress themes which use elements with a quite high Z index which hide the controls of PhotoSwipe. By setting the Z index of the affected controls to the highest possible value, all controls stay visible in front.

2) There are four skins, which you can choose from. Every skin is based on the default UI with some modifications. «New share symbol» contains a modified «share» symbol while «solid» in the name indicates, that all controls have a solid background instead of a slight transparency.

3) When dragging the picture to the top, there is no additional fade out animation when closing the picture.

4) When looping is disabled, this also applies to the desktop view.

5) The grey placeholder for images when opening the lightbox is not visible (this was accomplished by adding display: none; for the placeholder).

6) Arrows for next and previous picture will be hidden for the first or last picture if no endless loop is activated.

7) When using full picture size in desktop view the UI elements will hide automatically and not only after a mouse movement and the image caption will also be hidden together with the navigation.

8) Full screen mode can also be activated by pressing the key «F» on the keyboard.

9) Gallery items support an optional «exif» property to display EXIF information in addition to the caption.

10) Infinite loop is also possible with only two images.

11) Added slide animation for changing images using the arrow buttons or via keyboard as suggested in


15 de enero de 2024 1 reply
El plugin es muy bueno, se ve excelente sin tocar nada y es de los pocos gratuitos que muestran datos EXIF y ahí también es donde tiene un problema, al igual que Meow Lightbox falla al momento de mostrar los EXIF de imágenes Webp.Por lo demás es lo mejor que usé y eso que probé realmente muchos, así que le dejo 5 estrellas, para mi si se arregla ese problema es el definitivo, poder usar webp y que muestre los EXIF sería una gran solución ya que baja mucho el peso de las imágenes.The plugin is very good, looks excellent without touching anything and is one of the few free ones that show EXIF data and that is also where it has a problem, like Meow Lightbox fails to display the EXIF of Webp images.For the rest is the best I used and that I really tried many, so I leave 5 stars, for me if that problem is fixed is the definitive, to use webp and show the EXIF would be a great solution because it greatly reduces the weight of the images.
10 de enero de 2024
In my opinion, this is the best Lightbox on Wordpress. It uses the famous PhotoSwipe, which has a clean, elegant and minimalistic look. The plugin offers an intuitive UI to adjust a few things and the developer is super responsive. Great work!
19 de septiembre de 2023
After adding PhotoSwipe on hardcoded websites, I am using this PhotoSwipe plugin for WordPress sites and it works fantastic. The configuration is well done. Thank you @awelzel . It's great, that dimsemenov allowed you to make this plugin. Keep it up!
Leer todas las 106 reseñas

Colaboradores y desarrolladores

«Lightbox with PhotoSwipe» es un software de código abierto. Las siguientes personas han colaborado con este plugin.


«Lightbox with PhotoSwipe» ha sido traducido a 5 idiomas locales. Gracias a los traductores por sus contribuciones.

Traduce «Lightbox with PhotoSwipe» a tu idioma.

¿Interesado en el desarrollo?

Revisa el código , echa un vistazo al repositorio SVN o suscríbete al registro de desarrollo por RSS.

Registro de cambios


  • Added option to disable image meta data caching in transients for special cases or debugging.


  • Make sure, that displaying SVG images in the lightbox is supported even if WordPress does not report it as allowed
    file type for upload (for example when not logged in as administrator).


  • Fixed handling of tabindex attribute in image links with Bricks image slider: if image links contain a tabindex
    attribute «-1», this was not treated as «no tabindex set» and could cause confusing image ordering when using
    image sliders which use the tabindex attribute to «hide» invisible images from keyboard navigation.


  • Updated WordPress compatibility information.


  • Additional handling of post content to avoid issues with dynamic page loading.


  • Updated handling of EXIF data shutter speed for fractional values with more than 1s.


  • Fix output of EXIF data shutter speed: instead of «123/1s» it will now be displayed as «123s» without «/1».
  • Use EXIF field «FocalLength» by default and not «FocalLengthIn35mmFilm».


PhotoSwipe 5 integration:

  • Updated PhtooSwipe to version 5.4.2.
  • Added desktop sliding similar to PhotoSwipe 4.


  • Fixed a compatibility issue with WPML. Images should now also be recognized as «local» when they are used on a translated version of the website.


  • Fixed typo in German translation


PhotoSwipe 5 integration:

  • Updated PhotoSwipe 5 to version 5.3.8.
  • Mouse wheel is now used for scrolling by default while zooming is done by holding the Ctrl key.
  • Zoom levels changed: initial zoom level is ‘fit’, secondary zoom level is ‘fill’ and maximum zoom level is 2.


  • Updated WordPress compatibility information.


  • Implemented backwards compatibility so PHP 5 won’t break the plugin.
  • Added PHP version to the info page including warnings about outdated versions.


  • Removed hooks for creating/deleting blogs as they are not needed any longer.


  • Fixed a problem using the WordPress API which could lead to issues with qTranslate-XT (thanks to Herr Vigg for the hint).
  • Optimized backend code.


PhotoSwipe 5 integration:

  • Adjusted style for overlay captions (.pswp__dynamic-caption--overlay) so they are easier to read on front of bright images.


  • Fixed a problem for sites which have a different URLs for site and frontend (thanks to Chris Whitford for the hint).



  • Added options for maximum image width/height.


  • Fixed missing header in backend settings.


  • Update translations.

PhotoSwipe 5 integration:

  • Added options to change background opacity and image padding.


  • Fix image width and height for images with EXIF rotation recorded in the IFD0 group.


  • Fixed checks for smaller image sizes if image is in portrait format.
  • Added explanation about opening transitions and image sizes in the «Info» tab.
  • Making translation easier by adding the translation domain as string and as plugin constant.
  • Backend settings with a more readable layout by using a limited maximum text width.


PhotoSwipe 4 integration:

  • Fixed a problem when using an URL fragment to open an image.


PhotoSwipe 5 integration:

  • Updated «fullscreen» plugin to use the updated UI handler registration.


  • Added filters for caption text parts.

PhotoSwipe 5 integration:

  • Updated «fullscreen» plugin to support iPad.


PhotoSwipe 5 integration:

  • Added translations for UI tooltip labels.
  • Updated plugins for «auto hide UI» and «fullscreen» to fix potential bugs and add translations.


PhotoSwipe 5 integration:

  • Reverted background click in desktop to the original «close lightbox» behaviour and made UI elements clickable even if hidden – as it was implemented in PhotoSwipe 4 – to avoid confusion when UI hides automatically in desktop mode.
  • Optimized frontend styles to include only one minimized file.


PhotoSwipe 5 integration:

  • Change background click action in desktop mode to «toggle controls» to avoid confusion when UI hides automatically in desktop mode.


  • Fix meta data handling for «external» images.


  • Using PhotoSwipe 5 with «overlay» caption by default.
  • Keep URL parameters in image links when reading image information for external images.
  • Fix bug when using image URLs with hash.

5.0.8 – 5.0.11

  • Several fixes in EXIF data handling.


  • Internal code refactoring.

PhotoSwipe 5 integration:

  • Updated dynamic caption plugin to version 1.2.6.
  • Hide dynamic caption if it is using «mobile» view instead of «aside» or «below» and the controls are hidden.


  • Fix wrong URL for smaller preview images if they exist.


PhotoSwipe 5 integration:

  • Do not display fullscreen button if the device does not support that.


PhotoSwipe 5 integration:

  • Create modules for fullscreen mode and automatic hiding the UI.
  • Keep dynamic caption always visible.


PhotoSwipe 5 integration:

  • Fixed caption hiding if there is nothing to display.
  • Fixed display of captions in «overlay» mode on mobile devices.
  • Added automatic hiding of captions in desktop mode.


  • Fixed a possible warning if an image has no preview size.


  • Minimum required WordPress version is now 5.3.
  • Added official release of PhotoSwipe 5 (thanks to Dmitry Semenov for his support!).
  • Added option to fix links to scaled images.
  • If possible PhotoSwipe will now be opened with lower resolution preview images for better performance.


  • Restore focus to the opening image after closing the lightbox.


  • Fixed calculation of fstop value in EXIF data for non apex values.


  • Fixed a potential problem when deleting a blog.


  • Fixed a bug which caused an error when trying to remove the plugin.


  • Removed «lazy loading» as this is not needed any longer.
  • Improved compatibility with older PHP versions (7.0 and up).


  • Removed Twig due to namespace conflicts with other plugins.


  • Removed cache table for image details and only use WordPress caching.


  • Changed requirements to at least WordPress 5.0 and PHP 7.4.
  • Added Composer and Twig for backend and optimized backend code.
  • Fixed a bug which could prevent the cache cleanup job to be scheduled.


  • Updated compatibility for WordPress 6.0.


  • Removed deprecated code in frontend.


  • Updated frontend to avoid problems with galleries like Meow which trigger DOM updates and remove event handlers on image links.

3.3.1, 3.3.2

  • Remove variable types in backend code to avoid problems on hosts with very old PHP version (older than PHP 7.3).


  • Refactored backend code.
  • Updated handling of captions to make it easier to understand what exactly is used for the caption.
  • Increased caption width to 960px.
  • Updated EXIF display styles.


  • Add using image title as caption.
  • Remove empty brackets in EXIF information where only the camera model but no other information is available.


  • Use correct size of the original image when «fix image link» option is enabled and image links got fixed.


  • Fix a bug which might cause image links to get removed when the «fix image link» option is enabled.


  • Add option to fix image links which contains size parameters. This can happen in Jetpack tiled gallery blocks.


  • Workaround to make sure that buttons styles are not changed by WP Dark Mode.


  • Fixed a potential warning/notice for non JPEG images when support for EXIF is enabled.


  • Added support for CDNs which use «pull mode» like ExactDN.


  • Fixed a potential problem in PhotoSwipe which can cause it to fail when RequireJS is present.


  • Removed support for Internet Explorer 9 or older in frontend script to avoid issues with current browsers.


  • Fixed a bug which caused the plugin to not work any longer when using the WordPress cache.


  • Add support for SVG images.


  • Image modification time is not checked any longer for external images to avoid warning messages in certain setups.


  • Updated skins to make sure that themes or plugins which include global styles for button don’t cause problems with the UI of PhotoSwipe.

= …