Jekyll One

Fulltext Search

The original lightbox script. Now with fluid animations and touch‑first gestures.

10-30 Minutes to read.

Getting started

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. Lightbox3 will auto-initialize on all [data-lightbox] elements.

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

Coming from Lightbox2

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

What changed Details

No jQuery

Lightbox3 is zero-dependency. Remove jQuery and the Lightbox2 plugin script.

Same data-lightbox

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

data-title still works

Lightbox3 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

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 Lightbox2 compatibility.

data-alt="text"

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

Initialization

Method Description

Lightbox.init(options?)

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

Options

Option Type Default Description

selector

string

'[data-lightbox]'

CSS selector for trigger elements.

springOpen

SpringConfig

{ stiffness: 260, damping: 26 }

Spring config for open and zoom-in animations.

springClose

SpringConfig

{ 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

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

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.

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

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

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 Sunset over the sea

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">
</a>

Custom springs

Select a preset, then click the image to feel the difference.

Mountains rising above a sea of clouds at sunset 
Lightbox.init({
  springOpen:  { stiffness: 260, damping: 24 },
  springClose: { stiffness: 300, damping: 28 },
});

Text links

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

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

Programmatic open

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

Open image via API

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

Events

Interact with any image above to see events logged here.

Interact with any image above... 
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));