simplelightbox

Touch-friendly image lightbox for mobile and desktop

Features

• Responsive
• Touch friendly
• Swipe gestures for next/previous image
• Easy to install, easy to use
• Minimalistic
• Only some css is included. You can change the style like you want!
• Lots of options
• Preloading next and previous image
• Android, iOs and Windows phone support
• CSS3 Transitions with fallback for older browsers
• Works in every modern Browser, even in IE 11
• Can use jQuery 1.x, 2.x and 3.x. This is not required.
• Keyboard support
• Pinch to zoom
• Double-tap to zoom

Install

// YARN
yarn add simplelightbox

// Bower
bower install simplelightbox

// NPM
npm install simplelightbox

After that include simple-lightbox(.min).css and simple-lightbox(.min).js to your page.

Usage

Standalone Plugin

When using the standalone variant (simple-lightbox(.min).js)

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

The jQuery-compatible (simple-lightbox.jquery(.min).js) variant works as before (v1.x):

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

With Webpack/Browserify/Parcel etc...

Choose the module file you want to import or require.

Module with Babel tranformation

import SimpleLightbox from "simplelightbox";

Plain ES Module without Babel

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

Markup

For the default setup, you just need links that are pointing to images.

<div class="gallery">
    <a href="images/image1.jpg"><img title="" alt="" src="images/thumbs/thumb1.jpg"></a>
    <a href="images/image2.jpg"><img title="Beautiful Image" alt="" src="images/thumbs/thumb2.jpg"></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 used by default to show a caption. For a complete example just look at the demo folder.

JavaScript Options

Events

Example

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

Public Methods

Example

var gallery = $('.gallery a').simpleLightbox();

gallery.next(); // Next Image

Multiple Lightboxes on one page

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

Customization

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;

Contributing

using gulp
Run gulp watch to enable continous watching of both src/simple-lightbox.js and src/simple-lightbox.scss. Both files will be compiled to dist/simple-lightbox.js and dist/simple-lightbox.css respectively. Open dist/index.html in your browser to inspect your changes...

Building
Just call gulp build to have all files and variants created inside dist!

Changelog

2.14.3 - Adding avif as format
2.14.2 - Fixing error with caption sibling matches and added option for captionHTML.
2.14.1 - Fixing #314. The captionSelector was to heavy. To not break #61 again I wrote a workaround for css + & > selectors
2.14.0 - Merging #309 - thank to @romain25, fixing #305 - removeChild error if overlay option is disabled.
2.13.0 - Fixing #281 close lightbox on load,#311 caption not working, #307 second time opening not working with download option, #310 - passive scroll event default warning in console.
2.12.1 - Fixing #292. Error with download-link
2.12.0 - Merging #283. Fixing className whitespace error. Thanks to @MVogge. Merging #287, which fixes #286 thanks to @majid-1xinternet. Added download option. Thanks to @cnotin
2.11.0 - Added possibility to add multiple classes to captions #280, added possibility for better selectors which fixes #62 again, fixed #268 lightbox not centered with scrolling
2.10.4 - Fixed #277 - add passive listener for scroll events, #276 mistake z-index
2.10.3 - Fixed #264 - Fixed wrong mouse-zoom when the page is scrolled
2.10.2 - Fixed #258 with opacity flicker on overlay. For this, moved style option captionOpacity to js plugin
2.10.1 - Fixed #255 fast switching photos and #256 for hiding back and next buttons on loop: false
2.10.0 - Fixed #254 - Nav Buttons disappear and adding new method getLighboxData so get some useful data for #251
2.9.0 - Added mousescroll function with new options mouseScroll and mouseScrollFactor
2.8.1 - Fixed #250 - No closing if image load fails. #249 Disable scroll on Mac works now
2.8.0 - Fixed #235 - legacy file too big. #236 bad package.json and added support for passive event listeners #240. Thanks to @coderars for the issues and some code
2.7.3 - Fixed #232 - sourceAttr does not work. Thanks to @bivisual for the issue
2.7.2 - Fixed #231 - disableRightClick doesn't. Thanks to @DrMint for the fix
2.7.1 - Fixed #228 - no mouse swiping in firefox. Thanks to @DrMint for the fix
2.7.0 - Merged #206 which fixes #205. Thanks to @ocean90 for the idea and PR
2.6.0 - Added new option uniqueImages for #156, focus for #190 and fixed bug #200 issue closing during animation
2.5.0 - Added new option fadeSpeed. This will fix #147 and #186
2.4.1 - Added new simple-lightbox.legacy.js with IE 11 Support. Fixes #175, #178, #183 and some other bugs from 2.4.0
2.4.0 - Added new option for fixed elements class #195
2.3.0 - Merged Feature for ESM Modules. Thanks to Dmytro Hrynevych #180
2.2.2 - Fixed direct closing on load error #182
2.2.1 - Fixed bug #174 and problem with ES Modules
2.2.0 - Added ES Modules support, thanks to @seralichtenhahn for the PR. This fixed #164
2.1.5 - Fixed bug #169 open method with jQuery and #171 error while pan on mobile devices
2.1.4 - Fixed bug #168 doubletap zoom on touch devices
2.1.3 - Fixed bug in destroy method #167 and bug with html in navText #165
2.1.2 - Fixed additionalHtml bug #163
2.1.1 - Fixed captions bug #162
2.1.0 - Added rel grouping feature #16 and added rtl support #161
2.0.0 - Complete rewrite. Now uses modern ES6 javascript, without the need of jQuery. Can use jQuery anyway. Developers can use gulp with babel to contribute. Thanks to Mtillmann #129 for the implementation
1.17.3 - Fixed new chrome passive error #155
1.17.2 - Fixed caption keeps disappeared on double click #139 and added better close symbol #133
1.17.1 - Added webp in fileExt list #135, removed hardcoded a-tag in isValidLink function #134
1.17.0 - Merged pull request #132. Added double click to zoom for desktop browsers - Thanks to coderkan
1.16.3 - Merged pull request #126,#127 - Thanks to jieter
1.16.2 - Added featured #124 - Add a class to html element if lightbox is open
1.16.1 - Fixed pinch to zoom offset error on scrolling #123
1.16.0 - Pinch to Zoom feature for touch devices with new options doubleTapZoom and maxZoom #79
1.15.1 - Merged pull request #113,#114,#115 - Thanks to RaphaelHaettich and celsius-jochen
1.15.0 - Merged pull request #111, fixed #101 and added possibility to close lightbox on load #74
1.14.0 - Merged pull request #107 and #108. Thanks to RaphaelHaettich
1.13.0 - Added featured #92 and merged pull request #98 and #99. Thanks to RaphaelHaettich
1.12.2 - Bugfix for #89
1.12.1 - Bugfix for #88,#87 and remove bind/unbind #84
1.12.0 - New option captionClass #81, bugfix for #82
1.11.1 - Merged pull request #76. Thanks to walterebert, added support for images with parameters and file extension check #59
1.11.0 - New option for src of image. e.g data attribute #70
1.10.7 - Added Bootstrap compatibility #69
1.10.6 - Merged pull requests #65. Thanks to mstaniuk
1.10.5 - Merged pull requests #60 and #61. Thanks to slavanga
1.10.4 - Bugfix von #58
1.10.3 - Merged pull requests #55, #56 and #57. Thanks to karland
1.10.2 - Aligned navigation and close buttons #51, fixed image error bug #52
1.10.1 - Added support for jQuery 3.x #50
1.10.0 - Implemented feature-request #48, history back, some bugfixing and code styling
1.9.0 - Implemented feature-request #16, added rel option for grouping images
1.8.6 - Implemented feature-request #46, added refresh method
1.8.5 - Implemented feature-request #44
1.8.4 - Bugfix for #41 and added option for additional html inside images #40
1.8.3 - Bugfix for #38 and small other fix for loop false option
1.8.2 - Better bugfix for #33, finally fixing multiple lightbox on one page slowness issues!
1.8.1 - Bugfix for #31, #32 and #33
1.8.0 - New API Events (changed open to show) and little fix in function open() brought by Geoffrey Crofte and some other small bugfixes
1.7.2 - Bugfix von #25 and #27
1.7.1 - Bugfix von #22 with new option alertError and merged pull request #23
1.7.0 - Add support for fading between photos, Bugfix for single image navigation, option for caption delay
1.6.0 - Option for caption position. Disable prev or next arrow if loop is false and position is first or last.
1.5.1 - Bugfix for multiple lightboxes on one page
1.5.0 - Added options for disabling rightclick and scrolling, changed default prev- and next-button text
1.4.6 - Option for fileExt can now be false to enable pictures like example.com/pic/200/100
1.4.5 - Bugfix lightbox opening does not work on mobile devices
1.4.4 - Bugfix no drag&drop in FF, changed default close text, only output data if lightbox is opened
1.4.3 - Bugfix z-index for spinner to low, added sass files
1.4.2 - Bugfix for issue #2 - Drop Event does not fire when mouse leaves window
1.4.1 - The whole caption Selector is rewritten. You can now select an element and get its text, use data or attribute
1.4.0 - Caption Attribute can now be what, you want, or data-title. Fixed some small issues
1.3.1 - Bugfix: disable keyboard control if lightbox is closed
1.3.0 - Added current index indicator/counter
1.2.0 - Added option for captions attribute (title or data-title)
1.1.2 - Bugfix for looping images
1.1.1 - Bugfix for loading indicator and removed a log-event
1.1.0 - Added classname for lightbox wrapper and width/height ratio
1.0.0 - Initial Release

Author

Andre Rinas - Github

Contributors

Martin Tillmann
nicekiwi
helloilya
bitstarr
Geoffrey Crofte - Github
Karl Anders - Github
Raphael Hättich
Serafin Lichtenhahn
Jochen Sengier - Github
Dmytro Hrynevych
Dominik Schilling - Github
DrMint