@divclass/lightbox

v1.0.2

Published

8 days ago

Divclass Lightbox — modern, lightweight lightbox for images and inline content. Only 32 KB (≈11 KB gzipped). Touch-friendly, cross-browser, swipe & drag gestures, virtual slides, inline HTML, zero dependency.

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

🎯 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