Responsive Touch-enabled Image Lightbox Plugin

File Size: 5.6 MB
Views Total: 137727
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
Responsive Touch-enabled Image Lightbox Plugin

A flexible, responsive, mobile-friendly JavaScript plugin helps you create image lightbox and gallery lightbox on your desktop and mobile websites.


  • Responsive and touch friendly.
  • Image preloading and loading spinner.
  • CSS3 powered animations.
  • Keyboard / Touch swipe navigation.
  • Custom image aspect ratio.
  • Pinch or double tap/click to zoom.
  • Works as either JavaScript or jQuery plugin.

How to use it:

1. Load the simple-lightbox.min.css in the header and the simple-lightbox.min.js in the footer section of the web page.

<link href="dist/simple-lightbox.min.css" rel="stylesheet" />
<!-- As A Vanilla JavaScript Plugin -->
<script src="dist/simple-lightbox.min.js"></script>
<!-- For legacy browsers -->
<script src="dist/simple-lightbox.legacy.min.js"></script>
<!-- As A jQuery Plugin -->
<script src="/path/to/cdn/jquery.min.js"></script>
<script src="dist/simple-lightbox.jquery.min.js"></script>

2. Insert all your images into a gallery container. The plugin will automatically generate captions from alt attribute of img tag. To group images, just add the rel attribute to the links as follows:

<div class="gallery"> 

  <a href="1.jpg" class="big" rel="rel1">
    <img src="thumb1.jpg" alt="" title="Image 1">

  <a href="2.jpg" class="big" rel="rel1">
    <img src="thumb2.jpg" alt="" title="Image 2">

  <a href="3.jpg" class="big" rel="rel2">
    <img src="thumb3.jpg" alt="" title="Image 3">

  <a href="4.jpg" class="big" rel="rel2">
    <img src="thumb4.jpg" alt="" title="Image 4">

3. Call the plugin with default options to enable the lightbox.

// As A Vanilla JavaScript Plugin
var gallery = new SimpleLightbox('.gallery a', { 
    /* options */ 

// As A jQuery Plugin -->
var gallery = $('.gallery a').simpleLightbox({
    /* options */

4. Full customization options with default values.

// default source attribute
sourceAttr: 'href',

// shows fullscreen overlay
overlay: true,

// shows loading spinner
spinner: true,

// shows navigation arrows
nav: true,

// text for navigation arrows
navText: ['&larr;','&rarr;'],

// shows image captions
captions: true,
captionDelay: 0,
captionSelector: 'img',
captionType: 'attr',
captionPosition: 'bottom',
captionClass: '',
captionHTML: false,

// captions attribute (title or data-title)
captionsData: 'title',

// shows close button
close: true,

// text for close button
closeText: 'X',

// swipe up or down to close gallery
swipeClose: true,

// show counter
showCounter: true,

// file extensions
fileExt: 'png|jpg|jpeg|gif',

// weather to slide in new photos or not, disable to fade
animationSlide: true,

// animation speed in ms
animationSpeed: 250,

// image preloading
preloading: true,

// keyboard navigation
enableKeyboard: true,

// endless looping
loop:  true,

// group images by rel attribute of link with same selector
rel: false,

// closes the lightbox when clicking outside
docClose:  true,

// how much pixel you have to swipe
swipeTolerance: 50,

// lightbox wrapper Class
className: 'simple-lightbox',

// width / height ratios
widthRatio: 0.8,
heightRatio: 0.9,

// scales the image up to the defined ratio size
scaleImageToRatio: false,

// disable right click
disableRightClick: false,

// disable page scroll
disableScroll: true,

// show an alert if image was not found
alertError:  true,

// alert message
alertErrorMessage: 'Image not found, next image will be loaded',

// additional HTML showing inside every image
additionalHtml: false,

// enable history back closes lightbox instead of reloading the page
history: true,

// time to wait between slides
throttleInterval: 0,

// Pinch to Zoom feature for touch devices
doubleTapZoom: 2,
maxZoom: 10,

// adds class to html element if lightbox is open
htmlClass: 'has-lightbox',

// RTL mode
rtl: false,

// elements with this class are fixed and get the right padding when lightbox opens
fixedClass: 'sl-fixed',

// fade speed in ms
fadeSpeed: 300,

// whether to uniqualize images
uniqueImages: true,

// focus the lightbox on open to enable tab control
focus: true,

5. API methods.

// Opens the lightbox; 

// Closes the lightbox

// Goto next image; 

// Goto previous image

// re-init the lightbox

// get lightbox data

// Destroys the lightbox

6. Events.

  • open.simplelightbox: fires before the lightbox opens
  • opened.simplelightbox: fires after the lightbox was opened
  • close.simplelightbox: fires before the lightbox closes
  • closed.simplelightbox: fires after the lightbox was closed
  • change.simplelightbox: fires before image changes
  • changed.simplelightbox : fires after image was changed
  • next.simplelightbox: fires before next image arrives
  • nextDone.simplelightbox: fires after next image was arrived
  • prev.simplelightbox: fires before previous image arrives
  • prevDone.simplelightbox: fires after previous image was arrived
  • nextImageLoaded.simplelightbox : fires after next image was loaded (if preload activated)
  • prevImageLoaded.simplelightbox : fires after previous image was loaded (if preload activated)
  • error.simplelightbox : fires on image load error
$('.gallery a').on('open.simplelightbox', function () {
  // do something…


v2.14.3 (2024-04-03)

  • Added support for avif format.

v2.14.2 (2023-09-01)

  • Fixing error with caption sibling matches and added option for captionHTML.

v2.14.1 (2023-05-26)

  • Bugfixes

v2.14.0 (2023-05-05)

  • Bugfixes

v2.13.0 (2023-03-29)

  • Bugfixes

v2.12.1 (2023-01-12)

  • Fixed an error with download-link

v2.12.0 (2023-01-12)

  • Bugfixes

v2.11.0 (2022-11-21)

  • Added possibility to add multiple classes to captions, added possibility for better selectors

v2.10.4 (2022-10-13)

  • Bugfixed

v2.10.3 (2022-03-21)

  • Fixed wrong mouse-zoom when the page is scrolled

v2.10.2 (2022-01-27)

  • Fixed small caption bug after last release

v2.10.1 (2021-11-16)

  • Bugs fixed

v2.10.0 (2021-11-10)

  • Fixed Nav Buttons disappear
  • Added new method getLighboxData

v2.9.0 (2021-09-30)

  • Added mouse-scroll feature.

v2.8.1 (2021-09-08)

  • Fixed scroll bug

v2.8.0 (2021-06-24)

  • Fixed right version number

v2.8.0 (2021-04-21)

v2.7.2 (2021-04-21)

  • Fixed sourceAttr does not work.

v2.7.2 (2021-04-14)

  • Fixed "disableRightClick" option no longer works

v2.7.1 (2021-04-13)

  • Fixed - no mouse swiping in firefox

v2.7.0 (2020-11-19)

  • Allow captionSelector to be a callback function which returns an element

v2.6.0 (2020-10-29)

  • Added new options: uniqueImages and focus
  • Fixed bugs

v2.5.0 (2020-10-21)

  • Added new option fadeSpeed. 

v2.4.1 (2020-10-19)

  • Added new simple-lightbox.legacy.js with IE 11 Support
  • Bugfixes

v2.4.0/v2.3.0 (2020-10-13)

  • Added new option for fixed elements class.

v2.2.2 (2020-09-29)

  • Fixed some bugs

v2.2.1 (2020-05-19)

  • Fixed: issue In Mobile When Touch Swipe Up or Down

v2.1.5 (2020-04-29)

  • Fixed: doubletap zoom on touch devices
  • Fixed: pan on mobile devices

v2.1.4 (2020-04-07)

  • Fixed: doubletap zoom on touch devices

v2.1.3 (2020-03-17)

  • Bugfixed

v2.1.2 (2020-02-26)

  • Fixed additionalHtml bug

v2.1.1 (2020-02-18)

  • Fixed captions bug

v2.1.0 (2020-02-17)

  • Added rel grouping feature


  • Fixed caption keeps disappeared on double click and added better close symbol


  • Added webp in fileExt list
  • Removed hardcoded a-tag in isValidLink function


  • Added double click to zoom for desktop browsers


  • If touchstart on image occurs on an A-tag, proceed to it's href


  • Add a class to html element if lightbox is open


  • Pinch to Zoom feature for touch devices with new options doubleTapZoom and maxZoom


  • Bugfixed


  • Bugfixed and added possibility to close lightbox on load


  • Fix overlay z-index


  • Set Imagecaption same with as image


  • Make overlay opacity configurable


  • Bugfix


  • Fixed bugs and removed bind/unbind


  • New option captionClass
  • Bug with refresh() and jquery 3.2.1


  • Thanks to walterebert, added support for images with parameters and file extension check


  • New option for src of image. e.g data attribute



  • Prevent default keyup action only if lightbox is opened


  • Add !default flag
  • Improve caption opacity


  • bugfixes


  • bugfixes


  • Aligned navigation and close buttons, fixed image error bug


  • Added support for jQuery 3.x


  • Add option to hash to the open lightbox for mobile sites
  • some bugfixing and code styling


  • added rel option for grouping images


  • Allows to re-init simpleightbox


  • Swipe top/bottom to close gallery


  • Fixed docClose issue on iPad
  • Added option for additional html inside images


  • bugfixes.


  • bugfixes.


  • New API Events (changed open to show) and little fix in function open() brought by Geoffrey Crofte and some other small bugfixes


  • more bugfix


  • bugfix


  • Add support for fading between photos
  • Bugfix for single image navigation


  • Option for caption position. 
  • Disable prev or next arrow if loop is false and position is first or last.


  • Bugfix for multiple lightboxes on one page


  • Added options for disabling rightclick and scrolling, changed default prev- and next-button text


  • Option for fileExt can now be false


  • Bugfix lightbox opening does not work on mobile devices


  • Bugfix no drag&drop in FF, changed default close text, only output data if lightbox is opened


  • Bugfix z-index for spinner to low, added sass files


  • Increase Z-Index
  • Fixed Drop Event does not fire when mouse leaves window


  • The whole caption Selector is rewritten. You can now select an element and get its text, use data or attribute


  • Caption Attribute can now be any attribute. Bugfixes


  • disable keyboard control if lightbox is closed


  • Added current index indicator/counter


  • Added option for captions attribute (title or data-title)


  • bugfix for looping

This awesome jQuery plugin is developed by andreknieriem. For more Advanced Usages, please check the demo page or visit the official website.