Lightbox V3

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

10-30 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.

The new version of Lightbox V2 (by Lokesh Dhakar) with fluid animations and touch‑first gestures.

A view of a town with mountains in the background

A view of a street with a lot of palm 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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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 thumbnails fade in instead of morphing from a source element.

HTML pattern:

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

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

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));