Migrating from 1.x to 2.x

Version 2.0.0 was a complete rewrite in modern ES6 JavaScript that no longer needs jQuery. The public surface kept its shape — the options, the event names and the methods — so on most sites only the line that creates the lightbox changes.

The 1.x series was a jQuery plugin through and through. Moving to 2.x removes that dependency from pages that only loaded jQuery for the lightbox, and it opens the door to ES modules and bundlers.

// 1.x: jQuery plugin
var lightbox = $('.gallery a').simpleLightbox({ loop: false });

// 2.x: standalone build
var lightbox = new SimpleLightbox('.gallery a', { loop: false });

// 2.x: jQuery build, same call as before
var lightbox = $('.gallery a').simpleLightbox({ loop: false });

If jQuery stays on the page and you do not want to touch the start-up code, load simple-lightbox.jquery.min.js instead of the standalone file. The old call keeps working unchanged.

For bundlers there are two entry points: import SimpleLightbox from "simplelightbox" for the module with Babel transformation, and "simplelightbox/dist/simple-lightbox.esm" for the plain ES module.

Event names are unchanged: show.simplelightbox, closed.simplelightbox and the rest. With the standalone build you listen on the object that new SimpleLightbox() returns:

var lightbox = new SimpleLightbox('.gallery a');

lightbox.on('shown.simplelightbox', function () {
    // the image is visible now
});

open, close, next, prev, destroy and refresh are available as before. One detail is easy to miss: refresh() only works when the lightbox was created with a selector string, because it rebuilds itself from that selector.

Existing options kept their meaning. These were added during the 2.x series and are worth a look while you migrate:

The standalone build targets current browsers. Sites that still have to serve Internet Explorer 11 can use simple-lightbox.legacy.min.js, available since 2.4.1. Remove any IE-specific workarounds you added around the 1.x plugin — the legacy build takes care of that.

1. Replace the old script and stylesheet with the 2.x files.
2. Change $(…).simpleLightbox() to new SimpleLightbox(), or load the jQuery build.
3. Attach event handlers to the returned object.
4. Create the lightbox with a selector string wherever you call refresh().
5. Test swiping, pinch zoom and closing on a phone.

The gallery below runs on 2.x with two of the newer options, fadeSpeed and scrollZoom:

• Working with captions
• Dynamic galleries and refresh()
• Touch, swipe and zoom settings

Or go back to the full list of options.