Shortcode Walkthrough: [lightbox]

This article was last updated on the January 2, 2017.

Each Stack has unique styling for individual Shortcodes. For complete reference and demonstration, please refer to these pages: Integrity, Renew, Icon, Ethos.


X affords you a great deal of flexibility when it comes to setting up lightboxes. Instead of being limited to one particular layout for how your photos and content must appear, you can get creative with the look of your pages and still have your lightbox function flawlessly. Below we’ll go through some common lightbox setups to show you how easy it is to get everything up and running.

How the [lightbox] Shortcode Works

Before we begin, it’s important to understand how the [lightbox] shortcode operates. The [lightbox] shortcode does not add any images or setup any layouts for your photos on your pages or posts. Instead, utilizing this shortcode inserts the <script> that powers the lightbox for any given element that it is set to target. Let’s take a moment and run through each of the attributes available for the [lightbox] shortcode:

  • selector – Accepts a unique selector used on <a> elements that should open their href value in a lightbox. We will discuss this in more detail later on.
  • deeplink – Set this to true to allow deeplinking, which provides direct links to each lightbox image. Defaults to false if nothing is set.
  • opacity – The opacity of the lightbox background. Acceptable values are between 0 and 1. Defaults to 0.85 if nothing is set.
  • prev_scale – The scale of the previous lightbox image. Acceptable values are between 0 and 1. Defaults to 0.85 if nothing is set.
  • next_scale – The scale of the next lightbox image. Acceptable values are between 0 and 1. Defaults to 0.85 if nothing is set.
  • prev_opacity – The opacity of the previous lightbox image. Acceptable values are between 0 and 1. Defaults to 0.65 if nothing is set.
  • next_opacity – The opacity of the next lightbox image. Acceptable values are between 0 and 1. Defaults to 0.65 if nothing is set.
  • orientation – The orientation of the lightbox. Choose between horizontal or vertical. Defaults to horizontal if nothing is set.
  • thumbnails – Set this to true to enable thubmnail navigation for your lightbox. Defaults to false if nothing is set.

Now that we have a better understanding of how each attribute of the [lightbox] shortcode functions, let’s setup a few examples to see everything in action.

Basic Lightbox Gallery Setup

Setting up a lightbox gallery is incredibly simple when used in conjunction with our [image] shortcode. Anytime you add a linked image using this shortcode, your links will automatically have the x-img-link class applied to them, which is the default selector used by the [lightbox] shortcode if nothing is entered for the selector attribute. Below is an example of a three image lightbox gallery:

[image src="image-1.jpg" link="true"]
[image src="image-2.jpg" link="true"]
[image src="image-3.jpg" link="true"]

You’ll notice at a bare minimum all we have to enter for the [image] shortcode is the src and link attributes. This will display the image on the page, wrap it in a link, and set that link’s destination to the image itself. While the href attribute should technically be filled out, it will default to the src value if nothing is set. Additionally, the lightbox_thumb attribute will default to the src value as well if nothing is set. This is only important if you want to display the thumbnail navigation with your lightbox. We will talk more about this attribute of the [image] shortcode later.

With regards to the [lightbox] shortcode in this example, you can see that we haven’t entered in any values for any of the attributes. Since we’re using it in along with the [image] shortcode, the proper selector is already setup, and if you already like the defaults of the lightbox, then you don’t have to customize it any further.

Lightbox Images with Captions

To add captions to your images, you’re going to need to take advantage of the lightbox_caption attribute on the [image] shortcode. Filling this out will add a small caption to the bottom of each of your lightbox items. Let’s see how we can incorporate this feature into our lightbox:

[image src="image-1.jpg" link="true" lightbox_caption="I'm the first image."]
[image src="image-2.jpg" link="true" lightbox_caption="I'm the second image."]
[image src="image-3.jpg" link="true" lightbox_caption="I'm the third image."]

Make sure that you only enter plain text into this attribute as HTML is not allowed. Now that we’ve mastered adding captions to our lightbox images, we’ll work on incorporating video into our galleries.

Video Lightbox Setup

Setting up video in our lightbox requires that we link out to the proper embed source. First we’ll demonstrate an example of how this works below, then we’ll explain how to locate the appropriate link for this feature:

[image src="image-1.jpg" link="true" href="//" lightbox_video="true"]
[image src="image-2.jpg" link="true" href="//" lightbox_video="true"]

Note that we’ve added two new attributes to the [image] shortcode, href and lightbox_video. The href attribute is where we will provide the link to the video embed, and the lightbox_video attribute is something we must specify to inform the script that we want to play a video for this item.

Sometimes users have a difficult time locating the proper link to use for these embed features, and to implement it properly for these lightboxes, there’s one additional step we have to take to get it just right. Below are the steps to follow for locating these links on YouTube and Vimeo, although idea still applies to any service you are wanting to show video from

How to Find Your YouTube Embed Link

Follow the steps below to properly locate your YouTube embed link:

  1. Go to the page of the video you want to share.
  2. Locate and select the Share link below the video player.
  3. Select Embed from the list of available options.
  4. Copy the link from the src attribute.
  5. Paste the copied link into the href attribute of your [image] shortcode.

How to Find Your Vimeo Embed Link

Follow the steps below to properly locate your Vimeo embed link:

  1. Go to the page of the video you want to share.
  2. Hover over the video and select Share.
  3. Find the Embed input and copy the link from the src attribute.
  4. Paste the copied link into the href attribute of your [image] shortcode.

Alternate Thumbnail Navigation Images

If you are using the thumbnail navigation feature of the lightbox, there may be times that you wish to display a different image than the one set for the src attribute of your [image] shortcode. If this is the case, you will want to take advantage of the lightbox_thumb attribute:

[image src="image-1.jpg" link="true" lightbox_thumb="image-1-thumb.jpg"]
[image src="image-2.jpg" link="true" lightbox_thumb="image-2-thumb.jpg"]
[image src="image-3.jpg" link="true" lightbox_thumb="image-3-thumb.jpg"]
[lightbox thumbnails="true"]

This is a great feature to use in conjunction with displaying videos as it gives you plenty of flexibility in what you want to display for your navigation items.

Multiple Lightbox Portfolios on One Page

If you want to setup multiple lightbox portfolios on one page, simply specify a unique class for each grouping of items and be sure to specify their selectors in the [lightbox] shortcode:

[image class="folio-1" src="image-1.jpg" link="true"]
[image class="folio-1" src="image-2.jpg" link="true"]
[image class="folio-1" src="image-3.jpg" link="true"]
[lightbox selector=".folio-1"]

[image class="folio-2" src="image-4.jpg" link="true"]
[image class="folio-2" src="image-5.jpg" link="true"]
[image class="folio-2" src="image-6.jpg" link="true"]
[lightbox selector=".folio-2"]

Again, always be sure that your selector attribute matches the class you give to your items and that it is prepended with a dot (.) at the beginning of its name.

Mixing and Matching

Of course, you’re not always limited to one media type (i.e. photos or videos) in your lightbox portfolios. You can easily mix and match these elements to suit your needs:

[image src="image-1.jpg" link="true" lightbox_caption="I'm the first image."]
[image src="image-2.jpg" link="true" href="//" lightbox_video="true"]
[image src="image-3.jpg" link="true" lightbox_thumb="image-3-thumb.jpg"]
[lightbox thumbnails="true"]

Buttons and Lightboxes

As of v2.0.7 of the X Shortcodes plugin, this functionality is also available with buttons as well. The only difference in using the [lightbox] shortcode with buttons is that you must specify an href value (i.e. there is no fallback like the [image] shortcode), you must specify a lightbox_thumb value if you’re displaying the thumbnail navigation, and you must specify a selector for the [lightbox] shortcode. At the bare minimum, setting up a lightbox in conjunction with the [button] shortcode would look something like this:

[button href="image-1.jpg"]
[lightbox selector=".x-btn"]

The x-btn class is added to all buttons by default, so you can easily use this without needing to implement anything on your own. However, to avoid any potential conflicts with any other buttons on your page, it might be a good idea to add your own unique class to the [button] shortcode and use that instead:

[button class="btn-lightbox" href="image-1.jpg"]
[lightbox selector=".btn-lightbox"]

The same lightbox_thumb, lightbox_video, and lightbox_caption attributes are available for the [button] shortcode as well. For example, if you wanted to add a caption to an image linked out to by your button, it would look something like this:

[button class="btn-lightbox" href="image-1.jpg" lightbox_caption="I am a caption."]
[lightbox selector=".btn-lightbox"]

Should you have any further questions after reviewing this article, let us know in the forum so that we can work to improve the information provided.

[gallery] Shortcode Lightbox

The power and flexibility of the [lightbox] shortcode becomes even more evident as you begin to pair it not only with our shortcodes, but native WordPress shortcodes as well. A great example of how to take advantage of this would be to utilize the [gallery] shortcode, which automatically outputs a uniform grid of thumbnails onto your page. The following steps will walk you through how to include a gallery of images onto your page in the proper manner so that it can be used in conjunction with the [lightbox] shortcode:

  1. Click the Add Media button located directly above the editor to the left.
  2. Select the Create Gallery option in the upper left corner of the media manager.
  3. Choose the images that you would like to add to your gallery.
  4. Click the Create a new gallery button in the lower right corner of the media manager.
  5. Select Media File from the Link To dropdown in the upper right corner of the media manager and setup your other options as well.
  6. Click the Insert gallery button in the lower right corner of the media manager.

Depending on how many images you have chosen to add to your page, you should end up with something that looks like this:

[gallery link="file" ids="17560,17559,17558,17226,3318,3317,3121,3120,3119"]

Directly beneath this shortcode, place the [lightbox] shortcode with a value of .gallery-icon a in the selector attribute, like so:

[gallery link="file" ids="17560,17559,17558,17226,3318,3317,3121,3120,3119"]
[lightbox selector=".gallery-icon a"]