Divclass Lightbox

Lightweight 32 KB (≈11 KB gzipped), dependency-free lightbox for images and inline content.
Supports smart zoom animations, virtual slides, swipe & drag gestures, and works on all modern browsers and touch devices.

Live Demo

🌟 Key Features

Lightweight — 32 KB (≈11 KB gzipped)
Full-featured lightbox without heavy dependencies.
Virtual Slides
Only 3 DOM nodes exist at a time for optimal performance.
Fully Responsive
Works perfectly across desktop, tablet, and mobile devices.
Cross-browser & Touch-friendly
Supports modern browsers and touch gestures.
Easy Integration
Initialize via data attributes or selectors.
Smart Zoom From Origin
Smooth animation from thumbnail → full image without predefined image sizes.
Swipe & Drag Gestures
Intuitive navigation on touch devices
Animated Thumbnails & Data Galleries
Create galleries instantly using data-gallery.
Inline Content & Nested Modals
Display any HTML content and even open nested modals.
Smart Image Preloading
Smooth navigation with optimized image loading.
Keyboard Navigation
Global Controls
- DivclassLightbox.closeAll()
- DivclassLightbox.destroyAll()
Customizable Animations

🌍 Demo

https://lightbox.divclass.org

📦 Installation

Install via npm

npm install @divclass/lightbox

import DivclassLightbox from "@divclass/lightbox";
import "@divclass/lightbox/style.css"


new DivclassLightbox("[data-dc-lightbox]")

CDN

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@divclass/lightbox/dist/divclass-lightbox.css">
<script src="https://cdn.jsdelivr.net/npm/@divclass/lightbox/dist/divclass-lightbox.umd.js"></script>

<script>
  new DivclassLightbox('[data-dc-lightbox]');
</script>

ES Modules (browser)

<link rel="stylesheet" href="/path/divclass-lightbox.css">

<script type="module">
  import DivclassLightbox from "/path/divclass-lightbox.esm.js";

  new DivclassLightbox("[data-dc-lightbox]");
</script>

Manual Download

Download the latest release and include the files manually:

<link rel="stylesheet" href="dist/divclass-lightbox.css">

<script src="dist/divclass-lightbox.umd.js"></script>

<script>
  new DivclassLightbox('[data-dc-lightbox]');
</script>

🚀 Quick Start

Add the data-dc-lightbox attribute to links that should open in the lightbox.

<a href="image-large.jpg" data-dc-lightbox>
  <img src="image-thumb.jpg" alt="">
</a>

Initialize the lightbox with a selector:

import DivclassLightbox from "@divclass/lightbox";
import "@divclass/lightbox/style.css"

new DivclassLightbox("[data-dc-lightbox]")

Gallery

Group items into a gallery using the data-gallery attribute.

<a href="img1.jpg" data-dc-lightbox data-gallery="gallery1">
  <img src="thumb1.jpg" alt="">
</a>

<a href="img2.jpg" data-dc-lightbox data-gallery="gallery1">
  <img src="thumb2.jpg" alt="">
</a>

<a href="img3.jpg" data-dc-lightbox data-gallery="gallery1">
  <img src="thumb3.jpg" alt="">
</a>

Caption

Use data-caption to display text or HTML.

<a
  href="image.jpg"
  data-dc-lightbox
  data-caption="Lorem ipsum <p>Custom HTML caption</p>"
>
  <img src="thumb.jpg" alt="">
</a>

Inline Content

You can open any HTML element inside the lightbox.

<a href="#modal-content" data-dc-lightbox>
  Open modal
</a>

<div id="modal-content" style="display:none">
  <h2>Hello</h2>
  <p>This content is displayed inside the lightbox.</p>
</div>

You can also use data-src:

<button data-dc-lightbox data-src="#modal-content">
  Open modal
</button>

Open via JavaScript

You can also open the lightbox programmatically.

DivclassLightbox.show({
  src: "https://picsum.photos/id/10/800/1000/",
  type: "image",
  caption: "Test image",
});

Open inline content:

DivclassLightbox.show({
  src: "#modal-1"
});

Example with additional options:

DivclassLightbox.show({
  src: "https://picsum.photos/id/10/800/1000/",
  type: "image",
  caption: "Auto closing example",
  closeExisting: true,
  autoClose: 2000
});

⚙ Options

Option	Type	Default	Description
icon	string	SVG	Close button icon
thumbnailsIcon	string	SVG	Thumbnails toggle icon
arrowIcon	string	SVG	Arrow navigation icon
showThumbnailsOnOpen	boolean	`true`	Show thumbnails when gallery opens
backdropClick	"close" \| false	`"close"`	Close modal when clicking backdrop (inline only)
closeExisting	boolean	`false`	Closes any currently open lightbox before opening a new one.
parentContainer	string	`"body"`	CSS selector of the container element where the modal will be appended.
hideScrollbar	boolean	`true`	Hide body scrollbar when lightbox is open
effect	"fadeIn" \| "fadeInDown" \| "fadeInUp" \| "zoomIn"	`"fadeInUp"`	Opening animation
zoomImageFromOrigin	boolean	`true`	Animate image from thumbnail position
animationDuration	number	`400`	Opening/closing animation duration (ms)
autoClose	false \| number	`false`	Automatically close lightbox after specified time (ms)
type	"inline" \| "image"	`"inline"`	Default content type
caption	string \| false	`false`	Caption text or HTML
slideChangeDuration	number	`280`	Slide transition duration (ms)
slideOffset	number	`0.1`	Distance offset between slides during drag/swipe navigation. Accepts values from 0 to 1

HTML Data Attributes

Attribute	Description
`data-src`	Alternative source if the element is not a link with `href`. Can point to an inline element (`#modal`) or an image URL.
`data-close`	Closes the lightbox when the element is clicked. Useful for custom buttons. Can also be `data-close="close-all"` to close all previously opened lightboxes.
`data-type`	Content type: `"image"` or `"inline"`. Required if the `href` for an image has no extension.
`data-caption`	Caption for the image. Can include HTML tags.
`data-gallery`	Groups elements into a gallery by name `data-gallery="galleryName"`, enabling navigation between items and animated thumbnails.

🎯 Events

Divclass Lightbox provides lifecycle hooks that allow you to interact with the modal during different stages.

const lightbox = new DivclassLightbox('[data-dc-lightbox]');

lightbox.on("layoutReady", ({ modalRef }) => {
  const heading = modalRef.querySelector("h2");

  if (heading) {
    heading.innerHTML = "New Text";
  }
});

Available Events

Event	Description
`beforeLayoutOpen`	Fired before the modal layout is prepared
`layoutReady`	Fired when the layout is inserted into the DOM
`layoutOpened`	Fired when the modal becomes visible
`beforeLayoutClose`	Fired before the modal starts closing
`layoutClosed`	Fired after the modal is fully closed

🌐 Global Methods