LiteLight

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

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

How to use it

When a photo is open, you can move, zoom, and close.

  • Click any image (or text link) to open the lightbox
  • Arrow keys move within the open gallery
  • Swipe left or right on mobile
  • Pinch-to-zoom and pan the image — the page behind stays put
  • ESC or click outside the image to close
  • X closes from the overlay control

Add it in 3 steps

  1. Install and import

    Install the package. Import the script and the stylesheet. The CSS is a separate file.

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

    Use a module script when you are not using a bundler.

    <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.3.0/dist/lite-light.min.css">
    <script type="module">
      import { init } from 'https://unpkg.com/litelight-js@1.3.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.3.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

    Put the full-size URL on data-lightbox. Use src for the thumbnail.

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

    A link can open the image. init() watches images only, unless you set imageSelector.

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

    Images with no data-lightbox-group share one gallery. The same name stays together. One image in a group opens alone. You still call init() once.

    <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>
  3. Call init() once

    Call init() once, after the images are in the page. Calling it again does nothing.

    init();

    In React, Vue, or Svelte, call init() after the images render. See the framework examples. It runs in Chrome 61+, Firefox 60+, Safari 10.1+, and Edge 79+.

Optional configuration

These are the defaults. Leave them out unless you need a change.

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

The separate galleries demo shows data-lightbox-group on one image and on a parent.

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

What's new in LiteLight 1.3.0

  • Add data-lightbox-group so one page can hold separate galleries
  • A group of one image opens alone
  • Triggers without the attribute still share one gallery

Frequently asked questions about this vanilla JS lightbox

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

How LiteLight compares

LiteLight adds no other library. The script and CSS are about 4 KB gzip.

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