Tutorial: Lightboxes

This tutorial will explain how to customize the appearance of lightboxes, as well as how to use Tumblr’s built-in function to create a lightbox in the absence of a photoset.

Part I.
Appearance

I’ll begin by including the html structure of a lightbox. I’ve shortened it to make it clearer to read and to serve as a reference, but you can view the full version in the developer panel (open a lightbox, then right click, inspect element). 

<div class="tmblr-lightbox">
        <div class="lightbox-caption hide"></div>
    <div class="vignette"></div>
    <div class="lightbox-image-container">
        <img class="lightbox-image">
    </div>
</div>

This is the new, updated version. In the customize page, the divs and images may still have the old ids. I’ve included both in the css below for your convenience.

To set a background for the lightbox, the first thing you need to do is hide the background image and remove other decorations in the css, like so:

.vignette, #vignette {
    opacity:0;
}
.lightbox-image, #tumblr_lightbox img {
    box-shadow:none !important;
    border-radius:0 !important;
    max-width:none;
}

You will need to override the original background color of the lightbox by including !important after your desired color:

.tmblr-lightbox, #tumblr_lightbox {
    background-color:rgba(245,245,245,.98) !important;
}

If you want to add borders to the images, here is an example of what the code should look like:

.lightbox-image, #tumblr_lightbox img {
    border:5px solid #fff !important;
    -moz-box-sizing:border-box;
    box-sizing:border-box;
}

Lastly, if you want to do something to the captions, for example hide them, use the following selectors:

.lightbox-caption, #tumblr_lightbox_caption {
    visibility:hidden;
}

Part II.
Creating a lightbox for a single image

Say you wanted to make a lightbox appear when you click a single photo. To do this, you can insert the following code into your photo block:

<a href="#" onclick="Tumblr.Lightbox.init([{ width: {PhotoWidth-HighRes}, height: {PhotoHeight-HighRes}, low_res: '{PhotoURL-500}', high_res: '{PhotoURL-HighRes}' }]); $('body').toggleClass('tumblr_lightbox_active'); return false">
    <img src="{PhotoURL-HighRes}">
</a>

Explanation:

• Tumblr.Lightbox.init is Tumblr’s built-in function for lightboxes. The argument of this function is an array of objects.
• Objects are contained in curly brackets { } and separated by commas. The array is contained in square brackets [ ].
• Each object corresponds to an image. In this case, there is only one image, but in the next part, you will see how to add more.
• The image object has four properties: width, height, high_res, and low_res. High_res takes the URL of the highest resolution of the image, and low_res will take any of the 250px, 400px, or 500px resolutions to use (as I understand it) as a placeholder while the high-res image is loading.
• The second part of the script toggles a class called ‘tumblr_lightbox_active’ which disables scrolling while the lightbox is open.
• 'Return false’ disables the link so that you remain on the same page after you click it.

If this doesn’t work at first, make sure that jQuery is linked somewhere in your theme.

Part III.
Creating a lightbox for a photoset

For demonstration purposes, I will use the case when a photoset is displayed as a single image:

<a href="#" onclick="Tumblr.Lightbox.init([/*{block:Photos}, /**/ { width: {PhotoWidth-HighRes}, height: {PhotoHeight-HighRes}, low_res: '{PhotoURL-500}', high_res: '{PhotoURL-HighRes}' }{/block:Photos}]); $('body').toggleClass('tumblr_lightbox_active'); return false">
    {block:Photos}<img src="{PhotoURL-HighRes}"><!--{/block:Photos}-->
</a>

This is almost the exact same code as before, but with a couple of modifications to allow it to take more than one image. Note the use of opening and closing comments to hide the content that we don’t want to include, such as the first comma in the array and each image that comes after the first in the photo block. I think that playing with this code yourself is the best way to understand how it works. However, as I said, this is just an example, and I don’t recommend adding this feature to your theme if you wouldn’t otherwise.

If you have any questions, you can message me and I will do my best to help.