LiteLightbox

What is it?

This code aims to create a progressively enhanced, lightweight, Wikipedia-like lightbox plugin in vanilla JS. LiteLightbox is about 2.7 KB of raw minified JavaScript, at litelightbox.min.js (uncompressed!).

Additionally, for the default styling a la Wikipedia, there's around 5 KB of raw minified CSS, at litelightbox.min.css.

<link href="litelightbox.min.css" rel="stylesheet" type="text/css">
<script src="litelightbox.min.js"></script>

What's a lightbox? It's that thing where you see a thumbnail of an image and, when you click it, it expands into the full-resolution image.

Why should I use it? Well, ideally, you don't want to load huge, hundred-KB images into a user's browser unless they want to see them. So, instead, you can load small previews and wait for users to click on them to expand.

# Simplest example

This is a simple, common use case. No captions, just a simple image. The thumbnail is wrapped in an anchor, which acts as the fallback for users with JavaScript disabled.

Code for this example:

<a href="big-version.png" data-llb-src="big-version.png">
	<img src="small-version.png">
</a>

Alternatively, if your trigger is an anchor which links to the full-resolution image via href already, you don't need to write the path again into data-llb-src; instead, you can pass a value of "href" to it:

<a href="big-version.png" data-llb-src="href">
	<img src="small-version.png">
</a>

Don't forget your alt text! If the first child of the data-llb-src element is an <img> with alt text, then that alt text will be copied to the full-resolution image.

<a href="big-version.png" data-llb-src="href">
	<img src="small-version.png" alt="…">
</a>

To add an alt text specific to the full-resolution image, simply add the attribute data-llb-alt:

<a href="big-version.png" data-llb-src="href" data-llb-alt="…">
	<img src="small-version.png" alt="…">
</a>

# Lightbox captions

You can, of course, include captions in the lightbox. This is done via the data-llb-caption attribute. Note that lightbox captions do not show up in "thumbnail mode". They only appear when the lightbox is opened. Here's an example (click to see image attribution):

Photo taken on 8 June 2020 by User:Avelludo. Available at Wikimedia Commons.

Code for this example:

<a href="big-version.png" data-llb-src="href">
	<img src="small-version.png" alt="…">
</a>
<span data-llb-caption>
	(full-resolution caption)
</span>

The element with the data-llb-caption attribute will be hidden on the main page, and its contents will be placed inside a <figcaption> element in the lightbox.

Note that, to include a lightbox caption, the caption wrapper element (that is, the element with the data-llb-caption attribute) MUST be the next direct sibling of the element with the data-llb-src attribute. In this example, the <span data-llb-caption> element MUST come immediately after the <a data-llb-src> element.

Be aware of permitted contents in HTML. For example, a <div> element is not allowed inside a <p> element. So, when building your caption with custom HTML, make sure you're not breaking the DOM, so that your captions show up properly.

With lightbox captions, images can have two different contexts – a shortened caption that goes alongside the thumbnail, and a longer caption that appears with the lightbox.

Photograph of peanuts on a wooden table. — This caption is only visible on the thumbnail. Photo by Isai Dzib on Unsplash.

Code for this example:

<figure>
	<a href="big-version.png" data-llb-src="href">
		<img src="small-version.png" alt="…">
	</a>
	<div data-llb-caption>
		<p>(full-resolution caption 1)</p>
		<p>(full-resolution caption 2)</p>
	</div>
	<figcaption>
		(thumbnail caption)
	</figcaption>
</figure>

Note, again, that the element with the data-llb-caption attribute is the next direct sibling of the element with the data-llb-src attribute.

Alternatively, if you use data-llb-caption="visible", your caption can be the same for both the thumbnail and the lightbox.

A partially unpeeled banana. — This caption will appear both on the thumbnail and on the lightbox. Photo by Isai Dzib on Unsplash.

Code for this example:

<figure>
	<a href="big-version.png" data-llb-src="href">
		<img src="small-version.png" alt="…">
	</a>
	<figcaption data-llb-caption="visible">
		(caption for thumbnail and lightbox)
	</figcaption>
</figure>

# Galleries

You can create galleries by adding the data-llb-gallery attribute on the element that has data-llb-src. Once open, the lightbox will display arrows for navigation. The user may also press the arrow keys on the keyboard to flip through the gallery.

A Polaroid camera. — Photo by Patrick Ferretti on Unsplash.

A printed photograph on a wooden table. — Photo by Rirri on Unsplash.

A front-facing Polaroid camera. — Photo by Patrick Ferretti on Unsplash.

Code for this example:

<a href="big-1.png" data-llb-src="href" data-llb-gallery>
	<img src="small-1.png" alt="…">
</a>
<a href="big-2.png" data-llb-src="href" data-llb-gallery>
	<img src="small-2.png" alt="…">
</a>

Currently, each page can only have a single gallery; that is, every image tagged with data-llb-gallery will be part of the same gallery. A further customization option will be added in the future, allowing you to specify an identifier for each separate gallery you wish to create.

# No previews

This library works by hooking an "on click" event to an element with a data-llb-src attribute. This means that you don't need a thumbnail image to make it work. A simple anchor (<a>) will suffice: open big image.

Code for this example:

<a href="big-version.png" data-llb-src="href" data-llb-alt="…">
	open big image
</a>

Note that, since this example does not have an <img> element with alt text as its first child, the data-llb-alt attribute is used.

You could, in theory, use a button instead of an anchor, like this: Photo published on 12 June 2018 at Unsplash by Charles Deluvio.
Or any other element, like a <span>: example span Photo published on 12 June 2018 at Unsplash by Charles Deluvio.

Keep in mind that, in the event that the user does not have JavaScript turned on, anchors will maintain the native behavior of redirecting the user to the full-resolution image. Other elements, such as <button>s, may not have these benefits. Additionally, remember to make your trigger element accessible to keyboard users.