LiteLight

The simplest vanilla JS lightbox.
Zero dependencies and under 10KB

Install with npm install litelight-js.
Live demo · FAQ

How to use it

Once a photo is open, use the keyboard, a swipe, or the buttons on the overlay to move through that gallery, look closer, or close it.

  • Click any image, or the text link above, to open that photo over the page.
  • One thumbnail can stand in for a whole set. In the single thumbnail demo, arrows, swipe, and the next button still reach the photos that are hidden on the page.
  • Arrow keys move to the previous or next photo in the gallery that is open.
  • Swipe left or right on a phone to move to the next photo.
  • Pinch with two fingers to zoom in, then drag to look around the photo. The page behind the lightbox stays at its normal size.
  • Escape, or a click on the dark area around the photo, closes the lightbox.
  • X in the corner closes it as well.

Add it in 3 steps

  1. Install and import

    In your project folder, run npm install litelight-js. Then import the script and the stylesheet. The CSS is a separate file, and the lightbox has no layout without it, so keep the litelight-js/css import.

    npm install litelight-js
    
    import { init } from 'litelight-js';
    import 'litelight-js/css';
    CDN, download, or plain HTML

    If the page has no bundler, such as Vite or webpack, load LiteLight with a type="module" script tag instead of an import.

    <script type="module">
      import { init } from 'litelight-js';
      import 'litelight-js/css';
      // call init() after images are in the DOM — see step 3
    </script>

    CDN (unpkg):

    <link rel="stylesheet" href="https://unpkg.com/litelight-js@1.4.0/dist/lite-light.min.css">
    <script type="module">
      import { init } from 'https://unpkg.com/litelight-js@1.4.0/dist/lite-light.min.js';
      init();
    </script>

    Manual download: get dist/lite-light.min.js and dist/lite-light.min.css from the 1.4.0 release.

    <link rel="stylesheet" href="path/to/lite-light.min.css">
    <script type="module">
      import { init } from './path/to/lite-light.min.js';
      init();
    </script>

    init and initLiteLight are identical exports.

  2. Mark your images

    On each image, put the address of the large file in data-lightbox. Leave src as the smaller picture you want people to see on the page. alt is the description a screen reader reads, and it is also the description shown if the image fails to load.

    <img src="thumbnail.jpg" data-lightbox="full-size.jpg" alt="Description">
    Text-link triggers (1.2.0)

    A text link can open a photo the same way an image can. init() watches images only until you change imageSelector. Use a[data-lightbox] for links, or combine both selectors when the page has images and links.

    <a href="full-size.jpg" data-lightbox="full-size.jpg">View full image</a>
    
    init({ imageSelector: 'a[data-lightbox]' });
    // Or mix images and links:
    init({ imageSelector: 'img[data-lightbox], a[data-lightbox]' });
    Separate galleries (1.3.0)

    Without data-lightbox-group, every marked image on the page is one gallery. To split them, give each set its own name. Put that name on every image in the set, or put it once on a parent that wraps those images. A group with a single image opens by itself, with no previous or next button. You still call init() once for the whole page.

    <img src="shore.jpg" data-lightbox="shore-full.jpg" data-lightbox-group="shore" alt="Shore">
    
    <div data-lightbox-group="woods">
      <img src="path.jpg" data-lightbox="path-full.jpg" alt="Path">
      <img src="ridge.jpg" data-lightbox="ridge-full.jpg" alt="Ridge">
    </div>
    Single thumbnail (1.4.0)

    Add data-lightbox-cover when one photo should stay on the page and the rest of that set should open only inside the lightbox. Put it on the wrapper, or on every image in the set. Add data-lightbox-thumb to choose the visible photo. Without it, the first image stays. The hidden images remain in the HTML, so previous, next, swipe, and the arrow keys still reach them. A parent that holds only a hidden image, such as a figure, a list item, or a card, is hidden with that image. Give the set its own data-lightbox-group when it should stay separate from the other photos. init() hides those images once. It does not watch for images added later. Leave the attribute off and every image stays visible.

    <div data-lightbox-group="cabin" data-lightbox-cover>
      <img src="porch.jpg" data-lightbox="porch-full.jpg" alt="Porch" data-lightbox-thumb>
      <img src="kitchen.jpg" data-lightbox="kitchen-full.jpg" alt="Kitchen">
      <img src="loft.jpg" data-lightbox="loft-full.jpg" alt="Loft">
    </div>

    The single thumbnail demo shows one set with data-lightbox-thumb and one set that keeps the first image.

  3. Call init() once

    Call init() once, after the images are in the page. A second call does nothing, so do not call it again to change settings. If you add the images with JavaScript, call init() after those images exist. When a set uses data-lightbox-cover, that same call hides the extra images. Images added after init() stay visible.

    init();

    In React, Vue, or Svelte, call init() after the images have rendered, for example from useEffect or onMounted. The framework examples show each one. LiteLight runs in Chrome 61 and newer, Firefox 60 and newer, Safari 10.1 and newer, and Edge 79 and newer.

Optional configuration

These are the defaults, and you can leave them out. Pass an option only when you need a different selector, a different attribute name for the image, the group, the cover, or the thumbnail, a longer swipe, or a slower fade.

init({
  imageSelector: 'img[data-lightbox]', // triggers: img, a, or both
  imageUrlAttribute: 'data-lightbox',  // full-size image URL attribute
  swipeThreshold: 50,                  // swipe distance in px
  fadeAnimationDuration: 150,          // fade ms; sets --ll-duration
  groupAttribute: 'data-lightbox-group', // omit the attribute to keep one gallery
  coverAttribute: 'data-lightbox-cover', // omit the attribute to keep every trigger visible
  thumbAttribute: 'data-lightbox-thumb'  // omit it and the first trigger in a cover gallery stays visible
});

The separate galleries demo shows data-lightbox-group on one image, and again on a parent that wraps two images. The single thumbnail demo shows data-lightbox-cover with and without data-lightbox-thumb.

LiteLight — Vanilla JS Lightbox Technical Reference

LiteLight — Vanilla JS Lightbox (npm: litelight-js)

LiteLight opens a full-size image over the page. You add an HTML attribute and one small script. The script and CSS are under 10KB together, and the package has no other libraries.

JavaScript (ES6+, ESM)

Web Browser (Chrome 61+, Firefox 60+, Safari 10.1+, Edge 79+)

Install this vanilla JS lightbox via NPM: npm install litelight-js

CDN JS: https://unpkg.com/litelight-js@latest/dist/lite-light.min.js

CDN CSS: https://unpkg.com/litelight-js@latest/dist/lite-light.min.css

GitHub: https://github.com/byronjohnson/litelight

NPM: https://www.npmjs.com/package/litelight-js

MIT License — free for personal and commercial use, no attribution required

What it does

LiteLight opens a full-size image over the page. You add data-lightbox and call init() once. The package name is litelight-js.

What you do not load

There is no jQuery and no framework. Lightbox2 and FancyBox need jQuery. PhotoSwipe has no extra library and is larger to set up.

JS lightbox quick start code

// Install the vanilla js lightbox:
// npm install litelight-js

import { init } from 'litelight-js';
import 'litelight-js/css';
init();

// HTML: add data-lightbox to any image (or a[data-lightbox] with a custom imageSelector)
// <img src="thumb.jpg" data-lightbox="full.jpg" alt="Photo">
// <a href="full.jpg" data-lightbox="full.jpg">View image</a>

Vanilla JS lightbox configuration options

init({
  imageSelector: 'img[data-lightbox]', // CSS selector for triggers (img, a, or both)
  imageUrlAttribute: 'data-lightbox',   // attribute with full-size image URL
  swipeThreshold: 50,                   // swipe distance in px to navigate
  fadeAnimationDuration: 150,           // fade animation in milliseconds
  groupAttribute: 'data-lightbox-group', // omit the attribute to keep one gallery
  coverAttribute: 'data-lightbox-cover', // omit the attribute to keep every trigger visible
  thumbAttribute: 'data-lightbox-thumb'  // omit it and the first trigger in a cover gallery stays visible
});

What's new in LiteLight 1.4.0

  • Add data-lightbox-cover so a gallery can show one thumbnail on the page
  • Add data-lightbox-thumb to choose that thumbnail; otherwise the first image stays
  • Hidden images still open inside the lightbox. Pages without the attribute stay unchanged

Frequently asked questions about this vanilla JS lightbox

Full answers are on the FAQ, including a single on-page thumbnail, React, Vue, and Svelte, pinch-to-zoom, and PhotoSwipe and Lightbox2.

How LiteLight compares

LiteLight does not ask you to install jQuery or another library. The script and the CSS together are about 4 KB after gzip. The table below compares that with Lightbox2, FancyBox, and PhotoSwipe.

LiteLight 1.4.0, Lightbox2, FancyBox, and PhotoSwipe
Feature LiteLight Lightbox2 FancyBox PhotoSwipe
Dependencies None Requires jQuery Requires jQuery None
Bundle Size ~4 KB gzip (JS + CSS) ~100KB+ ~200KB+ ~50KB
Touch / Swipe ✓ ✗ ✓ ✓
Pinch-to-Zoom ✓ ✗ ✓ ✓
Keyboard Nav ✓ ✓ ✓ ✓
ES Modules ✓ ✗ ✗ ✓
TypeScript Types ✓ (included) ✗ ✗ ✓
CSS Custom-Property Theming ✓ ✗ Limited ✓
Setup Steps 3 4+ 4+ 5+
License MIT (free commercial use) MIT Commercial license needed MIT
npm install npm i litelight-js npm i lightbox2 npm i @fancyapps/ui npm i photoswipe