Install
Grab the latest CSS / JS files from the CDN: https://cdnjs.com/libraries/ekko-lightbox.
Or, with bower: bower install ekko-lightbox --save
Or, download the files directly: https://github.com/ashleydw/lightbox/tree/master/dist
Place this near on your page, probably near the end of the body section:
$(document).on('click', '[data-toggle="lightbox"]', function(event) {
event.preventDefault();
$(this).ekkoLightbox();
});
Then simply add data-toggle to your anchor tags.
<a href="https://unsplash.it/1200/768.jpg?image=251" data-toggle="lightbox">
<img src="https://unsplash.it/600.jpg?image=251" class="img-fluid">
</a>
Obviously, you need Bootstrap. Made for Bootstrap v4 but *should* work with v3.
Options
Options are passed down to the modal object so you can also use any of the original modal options.
Pass the options to the calling function as an object, or set defaults using $.fn.ekkoLightbox.defaults (excluding modal default options, notable: title, footer, remote)
| Name | type | default | description | data-* |
|---|---|---|---|---|
| leftArrow / rightArrow | html | ❮ / ❯ |
HTML for the arrows | |
| wrapping | boolean | true |
Whether the gallery should loop or not | |
| width / height | integer | Force the width / height | data-(width|height)="[0-9]+" |
|
| maxWidth / maxHeight | integer | 9999 | Limit the container width / height | data-(max-width|max-height)="[0-9]+" |
| alwaysShowClose | boolean | false |
Always show the close button, even if no title is present | |
| loadingMessage | html | A fancy loader | HTML injected for loading | |
| showArrows | bool | true | Disable the navigation overlay |
$(this).ekkoLightbox({
alwaysShowClose: true,
onShown: function() {
console.log('Checking our the events huh?');
},
onNavigate: function(direction, itemIndex)
console.log('Navigating '+direction+'. Current item: '+itemIndex);
}
...
});
The following options are specified per element.
| Name | Description | Example |
|---|---|---|
| remote | If you can't/don't want to set the href property of an element | data-remote="http://www...." |
| gallery | For grouping elements | data-gallery="gallery-name" |
| type | Force the lightbox into image/YouTube mode. | data-type="(image|youtube|vimeo)" |
| disable-external-check | Force the lightbox loading into an iframe. | data-disable-external-check="(true|false)" |
<a href="https://unsplash.it/1200/768.jpg?image=251" data-toggle="lightbox" data-gallery="example-gallery" data-type="image">
<img src="https://unsplash.it/600.jpg?image=251" class="img-fluid">
</a>
Events
Events can be hooked into, set the the same as options above.
| Name | Description |
|---|---|
| onContentLoaded | Fired when content (image/video/remote page etc) has been fully loaded. |
| onNavigate | Fired before navigating a gallery. |
| onShow/onShown/onHide/onHidden | Inherited from the bootstrap modal. |
Examples
Thanks to https://unsplash.it/ for the images.
- Single Image
- Image Gallery
- Limit Image Size
- Videos
- Gallery of Videos
- Mixed gallery
- Programmatically call
- Via
data-remote - Force type
- Hidden elements
- Remote content
- Disable wrapping
Single Image
Note: uses modal plugin title option via data-title, and the custom footer tag using data-footer
Image Gallery
Galleries are created by adding the data-gallery attribute.
Limit Image Size
Note: uses modal plugin limiting via data-max-width (or data-max-height)
Videos
YouTube
You can use various YouTube URL formats, the regex used is: /^.*(youtu.be\/|v\/|u\/\w\/|embed\/|watch\?v=|\&v=)([^#\&\?]*).*/
Tame Impala - Elephant (using youtu.be link)
Justin Bieber - Love Yourself (suppress related videos with &rel=0)
Vimeo
You cannot embed Vimeo videos using the standard url (ie http://vimeo.com/80629469); you must link to the embed source (ie player.vimeo.com/video/80629469). This will mean your link url - if the JavaScript fails, will open the full screen player (try opening the first link below in a new tab); the solution to this is to set the lightbox source directly - the second link below does this.
City Lights - from Colin Rich (using embed link)
City Lights - from Colin Rich (with reccommended data-remote setting)
Forcing width
Set the width of the video
Gallery of Videos
Mixed gallery
Programmatically call
These two examples are opened via the JavaScript at the bottom of the source.
$('#open-image').click(function (e) {
e.preventDefault();
$(this).ekkoLightbox();
});
$('#open-youtube').click(function (e) {
e.preventDefault();
$(this).ekkoLightbox();
});
Via data-remote
Neither of these are <a /> tags, so both rely on the data-remote attribute.
Force type
If the images you are linking to have no extension, the lightbox cannot detect that is an image; therefore you need to tell the lightbox what data-type it is.
Current allowed types are: ['image', 'youtube', 'vimeo', 'instagram', 'video', 'url']
Click here for an image, but with no extension.
This link is missing the type attribute, and will iframe the image.
This link is linking to a YouTube video, but forcing an image.
Hidden elements
Facebook style, only show a few images but have a large gallery
Remote content
Given a URL, that is not an image or video (including unforced types), load the content using an iFrame.
Disable wrapping
To disable wrapping, set `wrapping` to false when creating a gallery.
$(this).ekkoLightbox({ wrapping: false });