SimpleLightbox turns ordinary links to images into a full-screen, touch-friendly viewer. Point it at the anchors that wrap your thumbnails and it takes care of the rest: the overlay, the loading spinner, captions, arrow navigation, the image counter and the close button.
Since version 2.0 the library is written in modern ES6 JavaScript and no longer needs jQuery, although a jQuery variant is still available. The package also ships an ES module for bundlers and a legacy build for Internet Explorer 11.
rel attribute, several lightboxes per pageNew here? Try the live examples, get the files on the download page or read how to add the lightbox to WordPress and TYPO3.
To install SimpleLightbox you can do the following:
// YARN
yarn add simplelightbox
//Bower
bower install simplelightbox
//NPM
npm install simplelightbox
Simple include simple-lightbox.css and simple-lightbox.js to your page and use:
When using the standalone variant (`simple-lightbox(.min).js`)
var lightbox = new SimpleLightbox('.gallery a', { /* options */ });When using the jQuery variant (`simple-lightbox.jquery(.min).js`)
var lightbox = $('.gallery a').simpleLightbox({ /* options */ });Choose the module file you want do import or require.
Module with Babel tranformationimport SimpleLightbox from "simplelightbox";import SimpleLightbox from "simplelightbox/dist/simple-lightbox.esm";For the default setup, you just need links that are pointing to images.
<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>The markup inside the A-Tags can be whatever you want. In this example thumbnails of the big images. The Title Tag is by default used to show a caption. For a whole example just look at the demo folder.
| Property | Default | Type | Description |
|---|---|---|---|
| sourceAttr | href | string | the attribute used for large images |
| overlay | true | bool | show an overlay or not |
| overlayOpacity | 0.7 | float | the opacity of the overlay |
| spinner | true | bool | show spinner or not |
| nav | true | bool | show arrow-navigation or not |
| navText | ['←','→'] | array | text or html for the navigation arrows |
| captions | true | bool | show captions if availabled or not |
| captionSelector | 'img' | string or function | set the element where the caption is. Set it to "self" for the A-Tag itself or use a callback which returns the element |
| captionType | 'attr' | string | how to get the caption. You can choose between attr, data or text |
| captionsData | title | string | get the caption from given attribute |
| captionPosition | 'bottom' | string | the position of the caption. Options are top, bottom or outside (note that outside can be outside the visible viewport!) |
| captionDelay | 0 | int | adds a delay before the caption shows (in ms) |
| captionClass | '' | string | adds an additional class(es) to the sl-caption use space or comma to add multiple classes. |
| close | true | bool | show the close button or not |
| closeText | '×' | string | text or html for the close button |
| swipeClose | true | bool | swipe up or down to close gallery |
| showCounter | true | bool | show current image index or not |
| fileExt | 'png|jpg|jpeg|gif' | regexp or false | list of fileextensions the plugin works with or false for disable the check |
| animationSpeed | 250 | int | how long takes the slide animation |
| animationSlide | true | bool | weather to slide in new photos or not, disable to fade |
| preloading | true | bool | allows preloading next und previous images |
| enableKeyboard | true | bool | allow keyboard arrow navigation and close with ESC key |
| loop | true | bool | enables looping through images |
| rel | false | mixed | group images by rel attribute of link with same selector. |
| docClose | true | bool | closes the lightbox when clicking outside |
| swipeTolerance | 50 | int | how much pixel you have to swipe, until next or previous image |
| className | 'simple-lightbox' | string | adds a class to the wrapper of the lightbox |
| widthRatio | 0.8 | float | Ratio of image width to screen width |
| heightRatio | 0.9 | float | Ratio of image height to screen height |
| scaleImageToRatio | false | bool | scales the image up to the defined ratio size |
| disableRightClick | false | bool | disable rightclick on image or not |
| disableScroll | true | bool | stop scrolling page if lightbox is opened |
| alertError | true | bool | show an alert, if image was not found. If false error will be ignored |
| alertErrorMessage | 'Image not found, next image will be loaded' | string | the message displayed if image was not found |
| additionalHtml | false | string | Additional HTML showing inside every image. Usefull for watermark etc. If false nothing is added |
| download | false | string | Text for a download link below the image. If false nothing is added |
| history | true | bool | enable history back closes lightbox instead of reloading the page |
| throttleInterval | 0 | int | time to wait between slides |
| doubleTapZoom | 2 | int | zoom level if double tapping on image |
| maxZoom | 10 | int | maximum zoom level on pinching |
| htmlClass | has-lightbox | string | adds class to html element if lightbox is open. If empty or false no class is set |
| rtl | false | bool | change direction to rigth-to-left |
| fixedClass | sl-fixed | string | elements with this class are fixed and get the right padding when lightbox opens |
| fadeSpeed | 300 | int | the duration for fading in and out in milliseconds. Used for caption fadein/out too. If smaller than 100 it should be used with animationSlide:false |
| uniqueImages | true | bool | whether to uniqualize images or not |
| focus | true | bool | focus the lightbox on open to enable tab control |
| scrollZoom | true | bool | Can zoom image with mousewheel scrolling |
| scrollZoomFactor | 0.5 | float | How much zoom when scrolling via mousewheel |
| Name | Description |
|---|---|
| show.simplelightbox | this event fires before the lightbox opens |
| shown.simplelightbox | this event fires after the lightbox was opened |
| close.simplelightbox | this event fires before the lightbox closes |
| closed.simplelightbox | this event fires after the lightbox was closed |
| change.simplelightbox | this event fires before image changes |
| changed.simplelightbox | this event fires after image was changed |
| next.simplelightbox | this event fires before next image arrives |
| nextDone.simplelightbox | this event fires after next image was arrived |
| prev.simplelightbox | this event fires before previous image arrives |
| prevDone.simplelightbox | this event fires after previous image was arrived |
| nextImageLoaded.simplelightbox | this event fires after next image was loaded (if preload activated) |
| prevImageLoaded.simplelightbox | this event fires after previous image was loaded (if preload activated) |
| error.simplelightbox | this event fires on image load error |
let gallery = new SimpleLightbox('.gallery a');
gallery.on('show.simplelightbox', function () {
// do something…
});
gallery.on('error.simplelightbox', function (e) {
console.log(e); // some usefull information
});
// with jQuery nearly the same
let gallery = $('.gallery a').simpleLightbox();
gallery.on('show.simplelightbox', function () {
// do something…
});| Name | Description |
|---|---|
| open | Opens the lightbox with an given Element |
| close | Closes current openend Lightbox |
| next | Go to next image |
| prev | Go to previous image |
| destroy | Destroys the instance of the lightbox |
| refresh | Destroys and reinitilized the lightbox, needed for eg. Ajax Calls, or after dom manipulations |
var gallery = $('.gallery a').simpleLightbox();
gallery.next(); // Next Image
You can have multiple lightboxes on one page, if you give them different selectors. Here is a small example:
var lightbox1 = $('.lighbox-1 a').simpleLightbox();
var lightbox2 = $('.lighbox-2 a').simpleLightbox();
You can customize Simplelightbox by changing the style in simplelightbox.css.
If you are using SASS, you can customize Simplelightbox with the following variables
$sl-font-family: Arial, Baskerville, monospace;
$sl-overlay-background: #fff;
$sl-navigation-color: #000;
$sl-caption-color: #fff;
$sl-caption-background: #000;
$sl-counter-fontsize: 1rem;
$sl-caption-fontsize: 1rem;
$sl-close-fontsize: 3rem;
$sl-breakpoint-medium: 35.5em; // 568px, when 1rem == 16px
$sl-breakpoint-large: 50em; // 800px, when 1rem == 16px
$sl-arrow-fontsize-small: 2rem;
$sl-arrow-fontsize-medium: 3rem;
$sl-arrow-fontsize-large: 3rem;
$sl-img-border-small: 0 none;
$sl-img-border-medium: 0 none;
$sl-img-border-large: 0 none;
$sl-iframe-border-small: 0 none;
$sl-iframe-border-medium: 0 none;
$sl-iframe-border-large: 0 none;
$add-vendor-prefixes: true !default;
No. Since version 2.0 the library is plain JavaScript and works on its own. If your project already uses jQuery, the jQuery variant keeps the familiar $('.gallery a').simpleLightbox() call; both variants share the same options, events and methods.
Give the links of each gallery the same rel attribute and use one selector — links with different rel values are browsed separately. Alternatively, create one lightbox per gallery with its own selector, as shown under Multiple Lightboxes.
Yes. Keep the object returned by new SimpleLightbox() and call open(). Without an argument it starts with the first image; pass one of the gallery links to start with that photo instead.
By default from the title attribute of the thumbnail. The options captionSelector, captionType and captionsData switch the source to the alt text, a data attribute or the text of another element. The captions guide walks through each variant.
Yes. Call refresh() after new links have been added to the page. It rebuilds the lightbox from the selector it was created with, so the new photos join the gallery and the counter shows the right total.
All current desktop and mobile browsers. For Internet Explorer 11 use the legacy build that ships in the dist folder of the package.