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
<a href="https://unsplash.it/1200/768.jpg?image=250" data-toggle="lightbox" data-title="A random title" data-footer="A custom footer text">
<img src="https://unsplash.it/600.jpg?image=250" class="img-fluid">
</a>
Image Gallery
Galleries are created by adding the data-gallery attribute.
<div class="row justify-content-center">
<div class="col-md-8">
<div class="row">
<a href="https://unsplash.it/1200/768.jpg?image=251" data-toggle="lightbox" data-gallery="example-gallery" class="col-sm-4">
<img src="https://unsplash.it/600.jpg?image=251" class="img-fluid">
</a>
<a href="https://unsplash.it/1200/768.jpg?image=252" data-toggle="lightbox" data-gallery="example-gallery" class="col-sm-4">
<img src="https://unsplash.it/600.jpg?image=252" class="img-fluid">
</a>
<a href="https://unsplash.it/1200/768.jpg?image=253" data-toggle="lightbox" data-gallery="example-gallery" class="col-sm-4">
<img src="https://unsplash.it/600.jpg?image=253" class="img-fluid">
</a>
</div>
<div class="row">
<a href="https://unsplash.it/1200/768.jpg?image=254" data-toggle="lightbox" data-gallery="example-gallery" class="col-sm-4">
<img src="https://unsplash.it/600.jpg?image=254" class="img-fluid">
</a>
<a href="https://unsplash.it/1200/768.jpg?image=255" data-toggle="lightbox" data-gallery="example-gallery" class="col-sm-4">
<img src="https://unsplash.it/600.jpg?image=255" class="img-fluid">
</a>
<a href="https://unsplash.it/1200/768.jpg?image=256" data-toggle="lightbox" data-gallery="example-gallery" class="col-sm-4">
<img src="https://unsplash.it/600.jpg?image=256" class="img-fluid">
</a>
</div>
</div>
</div>
Limit Image Size
Note: uses modal plugin limiting via data-max-width (or data-max-height)
<a href="https://unsplash.it/1200/768.jpg?image=250" data-toggle="lightbox" data-max-width="600">
<img src="https://unsplash.it/600.jpg?image=250" class="img-fluid">
</a>
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)
<p><a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" data-toggle="lightbox">Justin Bieber - Love Yourself</a></p>
<p><a href="http://youtu.be/b0jqPvpn3sY" data-toggle="lightbox">Tame Impala - Elephant (using youtu.be link)</a></p>
<p><a href="https://www.youtube.com/watch?v=oyEuk8j8imI&rel=0" data-toggle="lightbox">Justin Bieber - Love Yourself</a> (suppress related videos with <code>&rel=0</code>)</p>
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)
<p><a href="http://player.vimeo.com/video/80629469" data-toggle="lightbox">City Lights - from Colin Rich (using embed link)</a></p>
<p><a href="http://vimeo.com/80629469" data-remote="http://player.vimeo.com/video/80629469" data-toggle="lightbox">City Lights - from Colin Rich</a> (with reccommended <code>data-remote</code> setting)</p>
<p><a href="http://instagram.com/p/BRCYe_wD9pV/" data-toggle="lightbox" data-title="Plug for our new service">Instagram</a></p>
<p>This also works with photos: <a href="//instagram.com/p/BRCdyxnjBsA/" data-toggle="lightbox">Instagram</a></p>
Forcing width
Set the width of the video
<p><a href="https://www.youtube.com/watch?v=e-ORhEE9VVg" data-toggle="lightbox">Taylor Swift - Blank Space (standard)</a></p>
<p><a href="https://www.youtube.com/watch?v=e-ORhEE9VVg" data-toggle="lightbox" data-width="640">Taylor Swift - Blank Space (640 x 360)</a></p>
<p><a href="https://www.youtube.com/watch?v=e-ORhEE9VVg" data-toggle="lightbox" data-width="1280">Taylor Swift - Blank Space (1280 x 780)</a></p>
Gallery of Videos
<a href="http://www.youtube.com/watch?v=k6mFF3VmVAs" data-toggle="lightbox" data-gallery="youtubevideos" class="col-sm-4">
<img src="http://i1.ytimg.com/vi/yP11r5n5RNg/mqdefault.jpg" class="img-fluid">
</a>
<a href="http://youtu.be/iQ4D273C7Ac" data-toggle="lightbox" data-gallery="youtubevideos" class="col-sm-4">
<img src="http://i1.ytimg.com/vi/iQ4D273C7Ac/mqdefault.jpg" class="img-fluid">
</a>
<a href="//www.youtube.com/embed/b0jqPvpn3sY" data-toggle="lightbox" data-gallery="youtubevideos" class="col-sm-4">
<img src="http://i1.ytimg.com/vi/b0jqPvpn3sY/mqdefault.jpg" class="img-fluid">
</a>
Mixed gallery
<a href="http://www.youtube.com/watch?v=k6mFF3VmVAs" data-toggle="lightbox" data-gallery="mixedgallery" class="col-sm-4">
<img src="http://i1.ytimg.com/vi/yP11r5n5RNg/mqdefault.jpg" class="img-fluid">
</a>
<a href="https://unsplash.it/1200/768.jpg?image=257" data-toggle="lightbox" data-gallery="mixedgallery" class="col-sm-4">
<img src="https://unsplash.it/600.jpg?image=257" class="img-fluid">
</a>
<a href="http://vimeo.com/80629469" data-remote="http://player.vimeo.com/video/80629469" data-toggle="lightbox" data-gallery="mixedgallery" class="col-sm-4">
<img src="http://b.vimeocdn.com/ts/458/070/458070637_200.jpg" class="img-fluid">
</a>
Programmatically call
These two examples are opened via the JavaScript at the bottom of the source.
<a href="https://unsplash.it/1200/768.jpg?image=258" id="open-image" class="col-6">
<img src="https://unsplash.it/600.jpg?image=258" class="img-fluid">
</a>
<a href="http://youtu.be/iQ4D273C7Ac" id="open-youtube" class="col-6">
<img src="http://i1.ytimg.com/vi/iQ4D273C7Ac/mqdefault.jpg" class="img-fluid">
</a>
$('#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.
<img src="https://unsplash.it/600.jpg?image=259" data-toggle="lightbox" data-remote="https://unsplash.it/1200/768.jpg?image=259" class="img-fluid col-6">
<img src="http://i1.ytimg.com/vi/b0jqPvpn3sY/mqdefault.jpg" data-toggle="lightbox" data-remote="https://www.youtube.com/embed/b0jqPvpn3sY" class="img-fluid col-6">
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.
<p><a href="https://unsplash.it/1200/768?image=260" data-title="Force image display" data-footer="The remote of this modal has no extension (https://unsplash.it/1200/768?image=260) but works because the type is forced." data-toggle="lightbox" data-type="image">Click here for an image, but with no extension.</a></p>
<p><a href="https://unsplash.it/1200/768?image=261" data-footer="Without the type forced, the lightbox will remote load the content" data-toggle="lightbox">This link is missing the type attribute, and will iframe the image.</a></p>
<p><a href="http://www.youtube.com/watch?v=b0jqPvpn3sY" data-toggle="lightbox" data-type="image">This link is linking to a YouTube video, but forcing an image.</a></p>
Hidden elements
Facebook style, only show a few images but have a large gallery
<a href="https://unsplash.it/1200/768.jpg?image=263" data-toggle="lightbox" data-gallery="hidden-images" class="col-4">
<img src="https://unsplash.it/600.jpg?image=263" class="img-fluid">
</a>
<a href="https://unsplash.it/1200/768.jpg?image=264" data-toggle="lightbox" data-gallery="hidden-images" class="col-4">
<img src="https://unsplash.it/600.jpg?image=264" class="img-fluid">
</a>
<a href="https://unsplash.it/1200/768.jpg?image=265" data-toggle="lightbox" data-gallery="hidden-images" class="col-4">
<img src="https://unsplash.it/600.jpg?image=265" class="img-fluid">
</a>
<!-- elements not showing, use data-remote -->
<div data-toggle="lightbox" data-gallery="hidden-images" data-remote="https://unsplash.it/1200/768.jpg?image=264" data-title="Hidden item 1"></div>
<div data-toggle="lightbox" data-gallery="hidden-images" data-remote="https://www.youtube.com/embed/b0jqPvpn3sY" data-title="Hidden item 2"></div>
<div data-toggle="lightbox" data-gallery="hidden-images" data-remote="https://unsplash.it/1200/768.jpg?image=265" data-title="Hidden item 3"></div>
<div data-toggle="lightbox" data-gallery="hidden-images" data-remote="https://unsplash.it/1200/768.jpg?image=266" data-title="Hidden item 4"></div>
<div data-toggle="lightbox" data-gallery="hidden-images" data-remote="https://unsplash.it/1200/768.jpg?image=267" data-title="Hidden item 5"></div>
Remote content
Given a URL, that is not an image or video (including unforced types), load the content using an iFrame.
<a href="https://unsplash.it/1200/768.jpg?image=250" data-toggle="lightbox" data-max-width="600">
<img src="https://unsplash.it/600.jpg?image=250" class="img-fluid">
</a>
Disable wrapping
To disable wrapping, set `wrapping` to false when creating a gallery.
$(this).ekkoLightbox({ wrapping: false });