LiteLight
The simplest vanilla JS lightbox.
Zero dependencies and under 10KB
Live demo
Click any photo below. It opens larger, over the page.
While it is open, the left and right arrow keys move through this set of eight photos. Press Escape, or click the dark area around the photo, to close it.
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
-
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 thelitelight-js/cssimport.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.jsanddist/lite-light.min.cssfrom 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>initandinitLiteLightare identical exports. -
Mark your images
On each image, put the address of the large file in
data-lightbox. Leavesrcas the smaller picture you want people to see on the page.altis 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 changeimageSelector. Usea[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 callinit()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-coverwhen 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. Adddata-lightbox-thumbto 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 afigure, a list item, or a card, is hidden with that image. Give the set its owndata-lightbox-groupwhen 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-thumband one set that keeps the first image. -
Call
init()onceCall
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, callinit()after those images exist. When a set usesdata-lightbox-cover, that same call hides the extra images. Images added afterinit()stay visible.init();In React, Vue, or Svelte, call
init()after the images have rendered, for example fromuseEffectoronMounted. 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-coverso a gallery can show one thumbnail on the page - Add
data-lightbox-thumbto 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.
| 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 |