- Install
- Usage
- Options
- Events
- Public Methods
- Multiple
- Customization

# Documentation

## Install

To install SimpleLightbox you can do the following:

    // YARN
    yarn add simplelightbox

    //Bower
    bower install simplelightbox

    //NPM
    npm install simplelightbox

Simple include simplelight-box.css and simple-lightbox.js to your page and use:

## Usage

### Standalone Plugin

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

    var lightbox = new SimpleLightbox('.gallery a', { /* options */ });

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

    var lightbox = $('.gallery a').simpleLightbox({ /* options */ });

### With Webpack/Browserify/Parcel etc...

Choose the module file you want do 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 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.

## JavaScript Options

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 to the sl-caption
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 | This can be used as an anchor rel alternative for Simplelightbox. This allows the user to group any combination of elements together for a gallery, or to override an existing rel so elements are not grouped together. Note: The value can also be set to 'nofollow' to disable grouping.
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

## Events

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

#### Examples

    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

Name | Description
--- | ---
open | Opens the lightbox with an given Element
openPosition | openPositionOpens the lightbox to specific position
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
getLighboxData | Get some useful lightbox data

#### 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;

## Changelog

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.
2.4.1 - Added new simple-lightbox.legacy.js with IE 11 Support
2.4.0 - Added new option for fixed elements class #195
2.3.0 - Merged Feature for ESM Modules. Thanks to Serafin Lichtenhahn #173
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 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 big 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
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. Thankt 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/
Contributors

Andre Rinas - Github

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