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:
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 */ });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 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 |
| 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 |
| getLighboxData | Get some useful lightbox data |
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;