simplelightbox turns a folder of links into a swipeable gallery

One selector, one constructor, no markup contract

The core of simplelightbox is a single call. You point it at a CSS selector and it takes over the links it matches:

new SimpleLightbox('.some-element a', { /* options */ });

There is no required class on the container and no required data attribute, which is what makes it droppable into an existing page. The default setup needs nothing more than links pointing at images, and the markup inside the anchor tags is free: a gallery of thumbnails is the example given, but the caption is taken from the title attribute by default, so a link can carry a title and no visible caption text.

The audience is a developer with a static or templated page and a set of images, who wants the zoom, swipe and overlay behaviour without writing a dialog component. The feature list is aimed at touch devices first: responsive layout, swipe gestures for next and previous image, pinch to zoom, double tap to zoom, and support claimed for Android, iOS and Windows phones. Keyboard support is there too, so a desktop user is not left behind.

Two things are deliberately left to the developer. Only some CSS is included, and the project states plainly that you can change the style as you want, which keeps the library from dictating a look but means the shipped appearance is a starting point rather than a design.

Two builds sit in dist/, and they are not the same thing

The package publishes more than one artefact and the choice matters at the point where you wire it in. The standalone variant is simple-lightbox.js or simple-lightbox.min.js, and it is initialised with the new keyword. The jQuery compatible variant is simple-lightbox.jquery.js or its minified form, and it works the way the 1.x line did:

$('.some-element a').simpleLightbox({ /* options */ });

jQuery is optional rather than required, and the feature list notes that jQuery 1.x, 2.x and 3.x all work, so an existing jQuery site can keep its dependency and use the compatible build, while a modern build can skip jQuery entirely.

For bundlers the project asks you to pick a file. A module with Babel transformation is imported from the package root:

import SimpleLightbox from "simplelightbox";

A plain ES module without Babel comes from a specific path in the distribution:

import SimpleLightbox from "simplelightbox/dist/simple-lightbox.esm"

The package metadata marks the package as type module, points main at dist/simple-lightbox.js, style at dist/simple-lightbox.css and module at dist/simple-lightbox.modules.js, and requires Node 22 or newer. So the file your build resolves by default is the UMD style main entry, and the ESM path is the one to import when you want tree shaking or no Babel step.

Captions are configurable down to the attribute they come from

The options table is where this library shows more care than its size suggests. The caption mechanism has three coupled settings. captionSelector defaults to img and takes a string or a function, and setting it to self points at the anchor element itself rather than an image inside it. captionType defaults to attr and can be set to attr, data or text, which decides whether the caption is read from an attribute, from a data attribute or from the element's own text content. captions itself is a boolean switch, and the nav and spinner options control whether the arrows and the loading spinner appear.

The navigation arrows are configurable as well, with navText defaulting to the left and right arrow entities, and they accept text or HTML, so a project can swap in inline SVG or a font icon. The overlay is a boolean with overlayOpacity at 0.7 by default, and sourceAttr defaults to href, which is the attribute the large image URL is read from. That last option is what lets the same script serve a gallery whose links carry the full size image while the visible content is a thumbnail.

None of these options are documented in prose anywhere in the README.

The touch path is the primary path

Where most lightboxes treat touch as an afterthought, this one is built around it. The listed behaviours are swipe gestures for next and previous image, pinch to zoom, double tap to zoom, and preloading of the next and previous image. Preloading is the detail that separates a smooth gallery from a slideshow that stutters: the neighbour images are already in the browser cache by the time the user swipes.

Animation is CSS3 transitions with a fallback for older browsers, and the feature list claims the library works in every modern browser, even IE 11. That is a claim about legacy browser support, and it tells you the code path exists, not that it is tested against current browsers. The touch features rely on the browser's own zoom and gesture handling, which is also why the CSS is expected to be adjusted by the project using it: the library ships enough to work, and the layout details are the integrator's job.

Keyboard support is listed as well, so a desktop visitor can move through a gallery without a mouse. The library does not document focus management or screen reader behaviour for the modal, and that absence matters for a public facing gallery, since the overlay is a dialog that the project does not describe as such to assistive technology.

First gallery: install, add markup, initialise

The install is a single package manager call, and the project lists yarn, bower and npm as the options:

npm install simplelightbox

After that, include simple-lightbox.css or simple-lightbox.min.css and simple-lightbox.js or simple-lightbox.min.js in the page. The markup is ordinary links, with the href carrying the large image and the img inside carrying the thumbnail:

<div class="gallery">
    <a href="images/image1.jpg"><img src="images/thumbs/thumb1.jpg" alt="" title=""></a>
    <a href="images/image2.jpg"><img src="images/thumbs/thumb2.jpg" alt="" title="Beautiful Image"></a>
</div>

Then initialise the plugin against the links you want to be lightbox targets:

new SimpleLightbox('.some-element a', { /* options */ });

You should see the overlay open on click, the caption read from the title attribute, and the previous and next images reachable by swipe or by the arrow keys. The repository ships a demo folder with index.html, onlyImages.html and demo.css, plus an img folder, which is the fastest way to see the full option set in action before wiring it into a real page.

The build is gulp, Browserify and Sass, and it is a separate job from the library

simplelightbox is authored in src/ and compiled into dist/ by a gulp pipeline, and the toolchain is visible in the package metadata rather than hidden in a service. The build script is gulp build, and the dependencies are gulp itself, gulp-babel, browserify, babelify, core-js, gulp-sass with sass, gulp-uglify, gulp-rename, gulp-tap, gulp-append-prepend and gulp-buffer, with Babel core and the class properties plugin as the transform layer. There is a .babelrc at the root and a bower.json for the legacy Bower channel, which the README still lists as an install option.

This is a small library with a real build system rather than a single hand written file, and the practical consequence for a consumer is that the dist files are the product. You install the published package and consume dist/, you do not run this toolchain. For a maintainer, it means a build that needs Node 22, a Sass step for the styles and a browserify bundle, all of which have to be reinstalled and kept in step with the source.

Compared with a native dialog approach, the difference in design is where the value comes from. Using the browser's own dialog element and a small script of your own gives you a dependency free overlay, but you then have to write the swipe handling, the pinch and double tap zoom, the neighbour preloading and the caption rules yourself, which is most of the library. A framework component library would give you the same behaviours inside a component tree, at the cost of a framework dependency and a template for every gallery. simplelightbox sits between the two: plain script, no framework, gestures included.

The newest tag is older than the newest commit

The published version in the package metadata is 2.14.3, and the release list shows v2.14.3 on 2024-04-03, preceded by v2.14.2 in August 2023 and v2.14.1 in May 2023. The repository itself is not archived, and the last push was on 2026-07-20, so the master branch has moved well past the most recent tag. Nothing in the repository indicates that a new release is imminent, and pinning 2.14.3 from npm gives you the state of the code as of April 2024, not the current master.

The licence is MIT, which is permissive and requires only that the copyright notice be kept when the library is bundled into other people's sites, and the project is distributed through npm, yarn and the older bower.json channel. The package metadata declares no typings, and the source is plain JavaScript with Babel applied at build time, so a TypeScript project will need its own declaration file.

The upgrade cost for a consumer is therefore near zero, since the library is loaded as a static asset with no server side component and no data migration. The cost falls on whoever wants the current master, because that means building from source with the gulp pipeline rather than installing a tag.

Editorial conclusion

simplelightbox fits a site that already ships plain JavaScript, wants a lightbox with real touch handling, and prefers a single constructor over adopting a component framework. It does not fit a team that needs typed APIs, a maintained release line or accessibility guarantees the project has not documented, because the package metadata ships no typings and the newest published tag is 2.14.3 from 2024-04-03 while master moved on 2026-07-20. Verify first which dist file your build actually loads, since simple-lightbox.js, simple-lightbox.esm and the jQuery variant behave differently, and check the options table for captionType and captionSelector before relying on captions.

Frequently asked questions

Official sources

1. andreknieriem/simplelightbox on GitHub
2. License: MIT
3. Project website
4. README
5. Releases