Jekyll One

Fulltext Search

The original lightbox script. Now with fluid animations and touch‑first gestures. A lightbox is a helper that displays enlarged, almost screen-filling versions of images.

5-10 Minutes to read

Getting started

A lightbox is a helper which displays enlarged, almost screen-filling versions of images while dimming the remainder of the page. The technique, introduced by Lightbox Version 2, gained widespread popularity thanks to its simple style. The term lightbox has been employed since then for JavaScript libraries to support such functionality.

Lightbox V3 is the successor of Lightbox V2 (by Lokesh Dhakar). The new version comes with fluid animations and touch‑first gestures built in.

A view of a town with mountains in the background A view of a street with a lot of palm trees Red and white bridge over the trees A view of a city from a hill above the clouds

Markup

Add data-lightbox to any <a> element. The href is the full-size image URL.

<a href="photo.jpg" data-lightbox>
  <img src="thumb.jpg">
</a>

To create a gallery, give each link the same data-lightbox value.

<a href="photo-1.jpg" data-lightbox="gallery">
  <img src="thumb-1.jpg">
</a>
<a href="photo-2.jpg" data-lightbox="gallery">
  <img src="thumb-2.jpg">
</a>

Script tag

Load the CSS and JavaScript directly. Lightbox V3 will auto-initialize on all [data-lightbox] elements.

<link rel="stylesheet" href="Lightbox V3.css">
<script src="Lightbox V3.min.js"></script>

Coming from Lightbox V2

Lightbox V3 uses the same markup pattern you already know — mostly the same HTML, way better UX.

What changed Details

No jQuery

Lightbox V3 is zero-dependency. Remove jQuery and the Lightbox V2 plugin script.

data-lightbox

Your existing data-lightbox and data-lightbox="gallery" attributes work as-is.

data-title

Lightbox V3 reads data-title for captions, so your existing markup carries over. You can also use data-caption.

New features

Pinch-to-zoom, swipe navigation, swipe-to-dismiss, spring animations — all built in, no configuration needed.

API reference

The API (Application Programming Interface) is the set of commands the Lightbox V3 module offers to control it from your own code. For everyday use, you do not need the API at all: adding the data-lightbox attribute to a link is all that is required. The API becomes useful when a page should react to the lightbox — for example, to open an image from a button click, or to run some code after an image was closed. The following sections describe the available data attributes, options, methods, and events. All code examples are written in plain JavaScript and can be copied as a starting point for your own pages.

Data attributes

Attribute Description

data-lightbox

Add to an <a> element to enable lightbox. The href is used as the full-res image URL.

data-lightbox=“name”

Group links into a navigable gallery. All links sharing the same value form a set.

data-caption=“text”

Caption text displayed below the image. Also accepts data-title for Lightbox V2 compatibility.

data-alt=“text”

Alt text for the full-size image. Falls back to the thumbnail’s alt attribute if not set.

Initialization

Before the lightbox can respond to clicks, the module has to be started once. This step is called initialization. In the J1 Template, the module is initialized automatically when the resource lightbox3 is enabled for a page, so no extra code is needed. Manual initialization is only required if custom options should be passed, or if the module is used outside of the J1 Template. Calling Lightbox.init() scans the page for all elements carrying the data-lightbox attribute and makes them clickable.

Method Description

Lightbox.init( { options } )

Initialize and return a singleton instance. Scans the DOM for data-lightbox data elements. Safe to call multiple times — returns the existing instance.

Options

Options change how the lightbox looks and behaves. They are passed as a JavaScript object to Lightbox.init() — for example, Lightbox.init({ padding: 20 }). Every option has a sensible default value, so passing options is entirely optional. The two spring settings control the physics of the animations: a higher stiffness makes the movement faster, while a higher damping reduces the bouncing at the end. The table below lists all supported options, their types, and their default values.

Option Type Default Description

selector

string

data-lightbox

CSS selector for trigger elements.

springOpen

object

{ stiffness: 260, damping: 26 }

Spring config for open and zoom-in animations.

springClose

object

{ stiffness: 500, damping: 38 }

Spring config for close and zoom-out animations.

padding

number

40

Viewport padding in pixels around the opened image.

debug

boolean

false

Show debug overlay with spring values and state. Also enabled via ?debug URL param.

Methods

Methods are commands you can run on the lightbox instance returned by Lightbox.init(). They allow you to open, close, and navigate the lightbox from your own code instead of waiting for a user click. A typical use case is a custom button that opens a specific image, or a slideshow that steps through a gallery automatically. Store the instance in a variable first — for example, const lb = Lightbox.init() — and then call the methods on that variable. The table below describes all available methods.

Method Description

open(src, triggerEl?)

Programmatically open an image. src is the full-res URL. Optional triggerEl enables the morph animation from that element. Without it, the image fades in.

close()

Close the lightbox.

next()

Navigate to the next image in the gallery.

prev()

Navigate to the previous image in the gallery.

destroy()

Remove all event listeners, cancel animations, and tear down the instance.

Events

Events are notifications the lightbox sends out when something happens — for example, when an image is opened, closed, or zoomed. Your own code can listen to these events and react to them, such as pausing a video while the lightbox is open. Listening to an event does not change the behavior of the lightbox itself; it only informs your code. Each callback receives a detail object with useful information about the current image. The table below lists all events the lightbox fires.

Subscribe with lb.on(event, callback) and unsubscribe with lb.off(event, callback). Callbacks receive a { src, triggerEl, index, total } detail object.

Event Description

open

Fired when the open animation starts.

opened

Fired when the open animation completes.

close

Fired when the close animation starts.

closed

Fired when the close animation completes and the overlay is removed.

navigate

Fired when navigating to a different image in a gallery.

zoomIn

Fired when zoom-in starts (tap or double-click).

zoomOut

Fired when zoom-out starts.

CSS custom properties

Override these on :root or any parent element to customize the lightbox appearance.

Property Default Description

--lb-backdrop-color

rgba(0, 0, 0, 0.95)

Overlay backdrop color.

--lb-image-border-radius

24px

Border radius of the opened image.

--lb-image-padding

40px

Padding between the image and viewport edges.

--lb-chrome-bg

rgba(24, 24, 24, 0.8)

Background color of the caption bar.

--lb-chrome-text

rgba(255, 255, 255, 0.9)

Text color in the caption bar.

--lb-chrome-font-size

15px

Font size in the caption bar.

--lb-chrome-padding

16px

Padding around the caption bar and nav arrows.

--lb-chrome-border-radius

48px

Border radius of the caption bar.

--lb-z-index

999999

Z-index of the lightbox overlay.

Examples

The following examples show the lightbox in action on real images. Each example demonstrates a common use case and includes the HTML markup needed to rebuild it on your own pages. All images are loaded from the Unsplash image service and can be replaced by your own image files. Click or tap any thumbnail to open the lightbox and try out the gestures. The examples work on desktop and mobile devices alike.

Mixed aspect ratios

Portrait, landscape, square. Thumbnails can be cropped to any aspect ratio and will seamlessly transition to the full-size image.

Sunlit mountain valley Ocean cliffs at sunset Lake with autumn trees Snow-capped peaks at night Volcanic landscape

Zoom & pan

Click or tap to zoom in. Pinch to zoom on touch. Drag to pan when zoomed.

Modern skyscraper glass facade looking up

HTML in captions

Captions support links and line breaks.

Snow-capped mountains with a valley and evergreen trees 
<a
  href="photo.jpg"
  data-lightbox
  data-caption="Photo by <a href='https://example.com'>Jane Doe</a>">
  <img
    src="thumb.jpg"
    alt="Caption text">
</a>

Text links

Links without image thumbnails fade in instead of morphing from a source element.

  • Cherry blossoms in bloom
  • Coral reef underwater
  • Lightning over the plains

Because of the missing image tag (<img> ), no captions are available.

HTML pattern

  <a
    href="https://images.unsplash.com/photo-1542224566-6e85f2e6772f?w=2400&q=80"
    data-lightbox="">
    Cherry blossoms in bloom
  </a>

Programmatic open

Open images from code. Without a trigger element, the image fades in from center. Open image via API.

const lb = Lightbox.init();
lb.open('https://example.com/photo.jpg');

Events

Interact with any image above to see events logged here.

const lb = Lightbox.init();
lb.on('open', (e) => console.log('open', e.detail));
lb.on('closed', (e) => console.log('closed', e.detail));
lb.on('navigate', (e) => console.log('navigate', e.detail));
lb.on('zoomIn', (e) => console.log('zoomIn', e.detail));
lb.on('zoomOut', (e) => console.log('zoomOut', e.detail));