Documentation: Free Lightbox

Getting started

Getting started is simple. Just upload the plugin or install from your WordPress admin dashboard and activate.

SET “LINK TO MEDIA FILE”. For both images and galleries, you will need to go to block settings and set it so those blocks “Link to media file.” For Images, you can find this setting in the toolbar above the block. For galleries, the setting is in the block settings on the sidebar.

Working with Images

The Block Editor: Image and Gallery Blocks

Insert an image or gallery block, and set “Link to Media File” in the block settings. That’s all you need to do.

Plugin Settings

Plugin settings live under “Lightbox” on the main dashboard menu. There are options for customizing appearance (colors, borders, padding, margin, showing a title/caption/infobar, navigation arrow style, etc) and behavior (slideshow speed, javascript in footer, pinch-zoom on mobile, etc). These should be self explanatory.

AUTODETECT. If you do not want images to me automatically detected and opened in the lightbox, disable the ‘Autodetect’ option in the Lightbox settings.

CHOOSE LIGHTBOX. At the top of the plugin settings page, there is an dropdown to choose a lightbox to use on your site. For now, you have two options: the long-standing free lightbox, and the new Pro lightbox (requires upgrade).

We strongly suggest you leave “Autodetect” and “Fit Images to Screen” enabled. If you disable “Fit images to screen”, large images will stretch outside the boundaries of your browser window.


You can use shortcodes to add galleries. To open images in the lightbox, include link="file". Galleries are automatically grouped by post ID. You can group them separately using the group attibute. Examples:

[gallery link="file" ids="1,2,3" group="mon"]
[gallery link="file" ids="4,5,6" group="tue"]

You can add a rel=”lightbox” attribute to any link tag to activate the lightbox. If you have a set of related images that you would like to group, simply include a group name in the rel attribute. Use the title attribute if you want to show a caption. Use the data-download-attribute to set a custom download link. Examples:

// Open an image in the lightbox from a thumbnail
<a href="images/image-1.jpg" rel="lightbox"><img src="images/thumbnail-1.jpg" /></a>

// Open an image in the lightbox from a text links
<a href="images/image-1.jpg" rel="lightbox">Open image</a>

// Adding a caption
<a href="images/image-1.jpg" rel="lightbox" title="This is a caption."><img src="images/thumbnail-1.jpg" /></a>

// Grouping images as a gallery
<a href="images/image-1.jpg" rel="lightbox[roadtrip]">image #1</a>
<a href="images/image-2.jpg" rel="lightbox[roadtrip]">image #2</a>
<a href="images/image-3.jpg" rel="lightbox[roadtrip]">image #3</a>

// Custom download link
<a href="image-medium.jpg" rel="lightbox" data-download="image-superlarge.jpg"> [...] </a>

To disable lightboxing of an image link, just set any other rel-attribute: rel=”nobox”.

Working with Non-Images

The free lightbox does not support opening videos, PDFs, other types of non-image media. For wider support, consider upgrading to LightPress Pro, which does have wide support for non-image media.


The free lightbox does not integrate out-of-the-box with other gallery plugins, block plugins, or other types of plugins. For more extensive integrations consider upgrading to LightPress Pro.

For infinite scroll and similar “endless pages”-plugin, they should call doLightbox(); whenever they loads new content. Most plugins have a setting for code that is called after each new page is loaded – just give it this:

if ( typeof doLightBox !== 'undefined' && typeof jQuery !== 'undefined') {


If you have problems with the free lightbox, please make sure you try these steps before asking for help.

  • Make sure your site is not throwing any javascript errors. Use your browsers javascript console to find out.
  • If you’re running a custom theme, always have wp_header(); just before the closing </head> tag of your theme, or you will break many plugins, which generally use this hook to reference JavaScript files. Always have wp_footer(); just before the closing </body> for the same reason.
  • Many JavaScript optimizers, combiners, minifiers, etc. conflict with wp_localize_script(), used to configure this plugin and many others. If you experience problems with jQuery Lightbox, please disable all JavaScript-optimizing plugins (Super Cache, W3 Total Cache, etc).
  • Standard troubleshooting: try disabling other plugins, one at a time and try the lightbox each time to identify plugin conflicts.
  • Revert to the default theme. Did it help? Fix your theme.
  • Search the forums before posting.

If you have worked through the steps above and still have issues, you can post questions on the support forums.