blueimp Gallery
Demo
blueimp Gallery Demo
Description
blueimp Gallery is a touch-enabled, responsive and customizable image and video
gallery, carousel and lightbox, optimized for both mobile and desktop web
browsers.
It features swipe, mouse and keyboard navigation, transition effects, slideshow
functionality, fullscreen support and on-demand content loading and can be
extended to display additional content types.
Setup
Lightbox setup
Copy the css, img and js directories to your website.
Include the Gallery stylesheet in the head section of your webpage:
<link rel="stylesheet" href="css/blueimp-gallery.min.css">
Add the following HTML snippet with the Gallery widget to the body of your
webpage:
<div id="blueimp-gallery" class="blueimp-gallery">
<div class="slides"></div>
<h3 class="title"></h3>
<a class="prev">‹</a>
<a class="next">›</a>
<a class="close">×</a>
<a class="play-pause"></a>
<ol class="indicator"></ol>
</div>
Include the Gallery script at the bottom of the body of your webpage:
<script src="js/blueimp-gallery.min.js"></script>
Create a list of links to image files, optionally with enclosed thumbnails and
add them to the body of your webpage, before including the Gallery script:
<div id="links">
<a href="images/banana.jpg" title="Banana">
<img src="images/thumbnails/banana.jpg" alt="Banana">
</a>
<a href="images/apple.jpg" title="Apple">
<img src="images/thumbnails/apple.jpg" alt="Apple">
</a>
<a href="images/orange.jpg" title="Orange">
<img src="images/thumbnails/orange.jpg" alt="Orange">
</a>
</div>
Add the following JavaScript code after including the Gallery script, to display
the images in the Gallery lightbox on click of the links:
<script>
document.getElementById('links').onclick = function (event) {
event = event || window.event;
var target = event.target || event.srcElement,
link = target.src ? target.parentNode : target,
options = {index: link, event: event},
links = this.getElementsByTagName('a');
blueimp.Gallery(links, options);
};
</script>
Controls
To initialize the Gallery with visible controls, add the CSS class
blueimp-gallery-controls to the Gallery widget:
<div id="blueimp-gallery" class="blueimp-gallery blueimp-gallery-controls">
<div class="slides"></div>
<h3 class="title"></h3>
<a class="prev">‹</a>
<a class="next">›</a>
<a class="close">×</a>
<a class="play-pause"></a>
<ol class="indicator"></ol>
</div>
Carousel setup
To display the images in an inline carousel instead of a lightbox, follow the
lightbox setup and add the CSS class
blueimp-gallery-carousel to the Gallery widget and remove the child element
with the close class, or add a new Gallery widget with a different id
to your webpage:
<div id="blueimp-gallery-carousel" class="blueimp-gallery blueimp-gallery-carousel">
<div class="slides"></div>
<h3 class="title"></h3>
<a class="prev">‹</a>
<a class="next">›</a>
<a class="play-pause"></a>
<ol class="indicator"></ol>
</div>
Add the following JavaScript code after including the Gallery script to
initialize the carousel:
<script>
blueimp.Gallery(
document.getElementById('links').getElementsByTagName('a'),
{
container: '#blueimp-gallery-carousel',
carousel: true
}
);
</script>
Keyboard shortcuts
The Gallery can be controlled with the following keyboard shortcuts:
- Return: Toggle controls visibility.
- Esc: Close the Gallery lightbox.
- Space: Toggle the slideshow (play/pause).
- Left: Move to the previous slide.
- Right: Move to the next slide.
Please note that setting the carousel option to true disables the
keyboard shortcuts by default.
Options
Default options
The following are the default options set by the core Gallery library:
var options = {
container: '#blueimp-gallery',
slidesContainer: 'div',
titleElement: 'h3',
displayClass: 'blueimp-gallery-display',
controlsClass: 'blueimp-gallery-controls',
singleClass: 'blueimp-gallery-single',
leftEdgeClass: 'blueimp-gallery-left',
rightEdgeClass: 'blueimp-gallery-right',
playingClass: 'blueimp-gallery-playing',
slideClass: 'slide',
slideLoadingClass: 'slide-loading',
slideErrorClass: 'slide-error',
slideContentClass: 'slide-content',
toggleClass: 'toggle',
prevClass: 'prev',
nextClass: 'next',
closeClass: 'close',
playPauseClass: 'play-pause',
typeProperty: 'type',
titleProperty: 'title',
urlProperty: 'href',
srcsetProperty: 'urlset',
displayTransition: true,
clearSlides: true,
stretchImages: false,
toggleControlsOnReturn: true,
toggleControlsOnSlideClick: true,
toggleSlideshowOnSpace: true,
enableKeyboardNavigation: true,
closeOnEscape: true,
closeOnSlideClick: true,
closeOnSwipeUpOrDown: true,
emulateTouchEvents: true,
stopTouchEventsPropagation: false,
hidePageScrollbars: true,
disableScroll: true,
carousel: false,
continuous: true,
unloadElements: true,
startSlideshow: false,
slideshowInterval: 5000,
index: 0,
preloadRange: 2,
transitionSpeed: 400,
slideshowTransitionSpeed: undefined,
event: undefined,
onopen: undefined,
onopened: undefined,
onslide: undefined,
onslideend: undefined,
onslidecomplete: undefined,
onclose: undefined,
onclosed: undefined
};
Event callbacks
Event callbacks can be set as function properties of the options object passed
to the Gallery initialization function:
var gallery = blueimp.Gallery(
linkList,
{
onopen: function () {
},
onopened: function () {
},
onslide: function (index, slide) {
},
onslideend: function (index, slide) {
},
onslidecomplete: function (index, slide) {
},
onclose: function () {
},
onclosed: function () {
}
}
);
Carousel options
If the carousel option is true, the following options are set to
different default values:
var carouselOptions = {
hidePageScrollbars: false,
toggleControlsOnReturn: false,
toggleSlideshowOnSpace: false,
enableKeyboardNavigation: false,
closeOnEscape: false,
closeOnSlideClick: false,
closeOnSwipeUpOrDown: false,
disableScroll: false,
startSlideshow: true
};
The options object passed to the Gallery function extends the default options
and also those options set via carousel mode.
Indicator options
The following are the additional default options set for the slide position
indicator:
var indicatorOptions = {
indicatorContainer: 'ol',
activeIndicatorClass: 'active',
thumbnailProperty: 'thumbnail',
thumbnailIndicators: true
};
Fullscreen options
The following are the additional default options set for the fullscreen mode:
var fullscreenOptions = {
fullScreen: false
};
Video options
Video factory options
The following are the additional default options set for the video factory:
var videoFactoryOptions = {
videoContentClass: 'video-content',
videoLoadingClass: 'video-loading',
videoPlayingClass: 'video-playing',
videoPosterProperty: 'poster',
videoSourcesProperty: 'sources'
};
YouTube options
Options for YouTube videos:
var youTubeOptions = {
youTubeVideoIdProperty: 'youtube',
youTubePlayerVars: undefined,
youTubeClickToPlay: true
};
Vimeo options
Options for Vimeo videos:
var vimeoOptions = {
vimeoVideoIdProperty: 'vimeo',
vimeoPlayerUrl: '//player.vimeo.com/video/VIDEO_ID?api=1&player_id=PLAYER_ID',
vimeoPlayerIdPrefix: 'vimeo-player-',
vimeoClickToPlay: true
};
Container and element options
The widget container option can be set as id string (with "#" as prefix) or
element node, so the following are equivalent:
var options = {
container: '#blueimp-gallery'
};
var options = {
container: document.getElementById('blueimp-gallery')
};
The slidesContainer, titleElement and indicatorContainer options can
also be defined using a tag name, which selects the first tag of this kind found
inside of the widget container:
var options = {
slidesContainer: 'div',
titleElement: 'h3',
indicatorContainer: 'ol'
};
It is also possible to define the container and element options with a more
complex
querySelector,
which is supported by IE8+ and all modern web browsers.
If the helper script is replaced with jQuery,
the container and element options can be any valid jQuery selector.
Property options
The options ending with "Property" define how the properties of each link
element are accessed.
For example, the urlProperty is by default set to href. This allows to
define link elements with href or data-href attributes:
<div id="links">
<a href="images/banana.jpg">Banana</a>
<a data-href="images/apple.jpg">Apple</a>
</div>
If the links are passed as JavaScript array, it is also possible to define
nested property names, by using the native JavaScript accessor syntax for the
property string:
blueimp.Gallery(
[
{
data: {urls: ['https://example.org/images/banana.jpg']}
},
{
data: {urls: ['https://example.org/images/apple.jpg']}
}
],
{
urlProperty: 'data.urls[0]'
}
);
API
Initialization
The blueimp Gallery can be initialized by simply calling it as a function with
an array of links as first argument and an optional options object as second
argument:
var gallery = blueimp.Gallery(links, options);
The links array can be a list of URL strings or a list of objects with URL
properties:
var gallery = blueimp.Gallery([
'https://example.org/images/banana.jpg',
'https://example.org/images/apple.jpg',
'https://example.org/images/orange.jpg'
]);
var gallery = blueimp.Gallery([
{
title: 'Banana',
href: 'https://example.org/images/banana.jpg',
type: 'image/jpeg',
thumbnail: 'https://example.org/thumbnails/banana.jpg'
},
{
title: 'Apple',
href: 'https://example.org/images/apple.jpg',
type: 'image/jpeg',
thumbnail: 'https://example.org/thumbnails/apple.jpg'
}
]);
The URL property name defined by each list object can be configured via the
urlProperty option. By default, it is set to href, which allows to pass
a list of HTML link elements as first argument.
For images, the thumbnail property defines the URL of the image thumbnail,
which is used for the indicator navigation displayed at the bottom of the
Gallery, if the controls are visible.
The object returned by executing the Gallery function (the gallery variable
in the example code above) is a new instance of the Gallery and allows to access
the public API methods provided by the Gallery.
The Gallery initialization function returns false if the given list was
empty, the Gallery widget is missing, or the browser doesn't pass the
functionality test.
API methods
The Gallery object returned by executing the Gallery function provides the
following public API methods:
var pos = gallery.getIndex();
var count = gallery.getNumber();
gallery.prev();
gallery.next();
gallery.slide(index, duration);
gallery.play(interval);
gallery.pause();
gallery.add(list);
gallery.close();
Videos
HTML5 video player
The Gallery can be initialized with a list of videos instead of images, or a
combination of both:
blueimp.Gallery([
{
title: 'Fruits',
href: 'https://example.org/videos/fruits.mp4',
type: 'video/mp4',
poster: 'https://example.org/images/fruits.jpg'
},
{
title: 'Banana',
href: 'https://example.org/images/banana.jpg',
type: 'image/jpeg',
thumbnail: 'https://example.org/thumbnails/banana.jpg'
}
]);
The Gallery uses the type property to determine the content type of the
object to display.
If the type property is empty or doesn't exist, the default type image is
assumed.
Objects with a video type will be displayed in a
HTML5 video element
if the browser supports the video content type.
For videos, the poster property defines the URL of the poster image to
display, before the video is started.
Multiple video sources
To provide multiple video formats, the sources property of a list object can
be set to an array of objects with href and type properties for each
video source. The first video format in the list that the browser can play will
be displayed:
blueimp.Gallery([
{
title: 'Fruits',
type: 'video/*',
poster: 'https://example.org/images/fruits.jpg',
sources: [
{
href: 'https://example.org/videos/fruits.mp4',
type: 'video/mp4'
},
{
href: 'https://example.org/videos/fruits.ogg',
type: 'video/ogg'
}
]
}
]);
It is also possible to define the video sources as data-attribute on a link
element in JSON array format:
<div id="links">
<a
href="https://example.org/videos/fruits.mp4"
title="Fruits"
type="video/mp4"
data-poster="https://example.org/images/fruits.jpg"
data-sources='[{"href": "https://example.org/videos/fruits.mp4", "type": "video/mp4"}, {"href": "https://example.org/videos/fruits.ogg", "type": "video/ogg"}]'
>Fruits</a>
</div>
YouTube
The Gallery can display YouTube videos for Gallery
items with a type of text/html and a youtube property
(configurable via YouTube options) with the YouTube
video-ID:
blueimp.Gallery([
{
title: 'A YouYube video',
href: 'https://www.youtube.com/watch?v=VIDEO_ID',
type: 'text/html',
youtube: 'VIDEO_ID',
poster: 'https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg'
},
{
title: 'Banana',
href: 'https://example.org/images/banana.jpg',
type: 'image/jpeg',
thumbnail: 'https://example.org/thumbnails/banana.jpg'
}
]);
If the href
and poster
properties are undefined, they are set automatically
based on the video ID.
Please note that the Gallery YouTube integration requires a browser with
postMessage
support, which excludes IE7.
Vimeo
The Gallery can display Vimeo videos for Gallery items
with a type of text/html and a vimeo property
(configurable via Vimeo options) with the Vimeo video-ID:
blueimp.Gallery([
{
title: 'A Vimeo video',
href: 'https://vimeo.com/VIDEO_ID',
type: 'text/html',
vimeo: 'VIDEO_ID',
poster: 'https://secure-b.vimeocdn.com/ts/POSTER_ID.jpg'
},
{
title: 'Banana',
href: 'https://example.org/images/banana.jpg',
type: 'image/jpeg',
thumbnail: 'https://example.org/thumbnails/banana.jpg'
}
]);
If the href
property is undefined, it is set automatically based on the
video ID.
Please note that the Gallery Vimeo integration requires a browser with
postMessage
support, which excludes IE7.
Additional Gallery elements
It is possible to add additional elements to the Gallery widget, e.g. a
description label.
First, add the desired HTML element to the Gallery widget:
<div id="blueimp-gallery" class="blueimp-gallery">
<div class="slides"></div>
<h3 class="title"></h3>
<p class="description"></p>
<a class="prev">‹</a>
<a class="next">›</a>
<a class="close">×</a>
<a class="play-pause"></a>
<ol class="indicator"></ol>
</div>
Next, add the desired element styles to your CSS file:
.blueimp-gallery > .description {
position: absolute;
top: 30px;
left: 15px;
color: #fff;
display: none;
}
.blueimp-gallery-controls > .description {
display: block;
}
Then, add the additional element information to each of your links:
<div id="links">
<a href="images/banana.jpg" title="Banana" data-description="This is a banana.">Banana</a>
<a href="images/apple.jpg" title="Apple" data-description="This is an apple.">Apple</a>
</div>
Finally, initialize the Gallery with an onslide callback option, to set the
element content based on the information from the current link:
blueimp.Gallery(
document.getElementById('links'),
{
onslide: function (index, slide) {
var text = this.list[index].getAttribute('data-description'),
node = this.container.find('.description');
node.empty();
if (text) {
node[0].appendChild(document.createTextNode(text));
}
}
}
);
Additional content types
By extending the Gallery prototype with new factory methods, additional content
types can be displayed. By default, blueimp Gallery provides the
imageFactory and videoFactory methods for image and video
content types respectively.
The Gallery uses the type property of each content object to determine which
factory method to use. The type defines the
Internet media type of the
content object and is composed of two or more parts: A type, a subtype, and zero
or more optional parameters, e.g. text/html; charset=UTF-8 for an HTML
document with UTF-8 encoding.
The main type (the string in front of the slash, text in the example above)
is concatenated with the string Factory to create the factory method name,
e.g. textFactory.
Example HTML text factory implementation
Please note that the textFactory script has to be included after the core
Gallery script, but before including the YouTube and Vimeo
integration plugins, which extend the textFactory implementation to handle
YouTube and Vimeo video links.
Please also note that although blueimp Gallery doesn't require
jQuery, the following example uses it for convenience.
Extend the Gallery prototype with the textFactory method:
blueimp.Gallery.prototype.textFactory = function (obj, callback) {
var $element = $('<div>')
.addClass('text-content')
.attr('title', obj.title);
$.get(obj.href)
.done(function (result) {
$element.html(result);
callback({
type: 'load',
target: $element[0]
});
})
.fail(function () {
callback({
type: 'error',
target: $element[0]
});
});
return $element[0];
};
Next, add the text-content class to the Gallery CSS:
.blueimp-gallery > .slides > .slide > .text-content {
overflow: auto;
margin: 60px auto;
padding: 0 60px;
max-width: 920px;
text-align: left;
}
With the previous changes in place, the Gallery can now handle HTML content
types:
blueimp.Gallery([
{
title: 'Noodle soup',
href: 'https://example.org/text/noodle-soup.html',
type: 'text/html'
},
{
title: 'Tomato salad',
href: 'https://example.org/text/tomato-salad.html',
type: 'text/html'
}
]);
jQuery plugin
jQuery plugin setup
The blueimp Gallery jQuery plugin registers a global click handler to open links
with data-gallery attribute in the Gallery lightbox.
To use it, follow the lightbox setup guide, but replace the
minified Gallery script with the jQuery plugin version and include it after
including jQuery:
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script src="js/jquery.blueimp-gallery.min.js"></script>
Next, add the attribute data-gallery to your Gallery links:
<div id="links">
<a href="images/banana.jpg" title="Banana" data-gallery>
<img src="images/thumbnails/banana.jpg" alt="Banana">
</a>
<a href="images/apple.jpg" title="Apple" data-gallery>
<img src="images/thumbnails/apple.jpg" alt="Apple">
</a>
<a href="images/orange.jpg" title="Orange" data-gallery>
<img src="images/thumbnails/orange.jpg" alt="Orange">
</a>
</div>
The onclick handler from the lightbox setup guide is not
required and can be removed.
HTML5 data-attributes
Options for the Gallery lightbox opened via the jQuery plugin can be defined as
HTML5 data-attributes on the Gallery
widget container.
The jQuery plugin also introduces the additional filter option, which is
applied to the Gallery links via
jQuery's filter method and allows to remove
duplicates from the list:
<div id="blueimp-gallery" class="blueimp-gallery" data-start-slideshow="true" data-filter=":even">
<div class="slides"></div>
<h3 class="title"></h3>
<a class="prev">‹</a>
<a class="next">›</a>
<a class="close">×</a>
<a class="play-pause"></a>
<ol class="indicator"></ol>
</div>
This will initialize the Gallery with the option startSlideshow set to
true.
It will also filter the Gallery links so that only links with an even index
number will be included.
Container ids and link grouping
If the data-gallery attribute value is a valid id string
(e.g. "#blueimp-gallery"), it is used as container option.
Setting data-gallery to a non-empty string also allows to group links into
different sets of Gallery images:
<div id="fruits">
<a href="images/banana.jpg" title="Banana" data-gallery="#blueimp-gallery-fruits">
<img src="images/thumbnails/banana.jpg" alt="Banana">
</a>
<a href="images/apple.jpg" title="Apple" data-gallery="#blueimp-gallery-fruits">
<img src="images/thumbnails/apple.jpg" alt="Apple">
</a>
</div>
<div id="vegetables">
<a href="images/tomato.jpg" title="Tomato" data-gallery="#blueimp-gallery-vegetables">
<img src="images/thumbnails/tomato.jpg" alt="Tomato">
</a>
<a href="images/onion.jpg" title="Onion" data-gallery="#blueimp-gallery-vegetables">
<img src="images/thumbnails/onion.jpg" alt="Onion">
</a>
</div>
This will open the links with the data-gallery attribute
#blueimp-gallery-fruits in the Gallery widget with the id
blueimp-gallery-fruits, and the links with the data-gallery attribute
#blueimp-gallery-vegetables in the Gallery widget with the id
blueimp-gallery-vegetables.
Gallery object
The gallery object is stored via
jQuery data storage
on the Gallery widget when the Gallery is opened and can be retrieved the
following way:
var gallery = $('#blueimp-gallery').data('gallery');
This gallery object provides all methods outlined in the API methods section.
jQuery events
The jQuery plugin triggers Gallery events on the widget container, with event
names equivalent to the gallery event callbacks:
$('#blueimp-gallery')
.on('open', function (event) {
})
.on('opened', function (event) {
})
.on('slide', function (event, index, slide) {
})
.on('slideend', function (event, index, slide) {
})
.on('slidecomplete', function (event, index, slide) {
})
.on('close', function (event) {
})
.on('closed', function (event) {
});
Requirements
blueimp Gallery doesn't require any other libraries and can be used standalone
without any dependencies.
You can also use the individual source files instead of the standalone minified
version:
<link rel="stylesheet" href="css/blueimp-gallery.css">
<link rel="stylesheet" href="css/blueimp-gallery-indicator.css">
<link rel="stylesheet" href="css/blueimp-gallery-video.css">
<script src="js/blueimp-helper.js"></script>
<script src="js/blueimp-gallery.js"></script>
<script src="js/blueimp-gallery-fullscreen.js"></script>
<script src="js/blueimp-gallery-indicator.js"></script>
<script src="js/blueimp-gallery-video.js"></script>
<script src="js/blueimp-gallery-youtube.js"></script>
<script src="js/blueimp-gallery-vimeo.js"></script>
The helper script can be replaced by jQuery v. 1.7+.
The fullscreen, indicator, video, youtube and vimeo source files are optional if
their functionality is not required.
The jQuery plugin requires
jQuery v. 1.7+ and the basic Gallery script, while the
fullscreen, indicator, video, youtube and vimeo source files are also optional:
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="js/blueimp-gallery.js"></script>
<script src="js/blueimp-gallery-fullscreen.js"></script>
<script src="js/blueimp-gallery-indicator.js"></script>
<script src="js/blueimp-gallery-video.js"></script>
<script src="js/blueimp-gallery-youtube.js"></script>
<script src="js/blueimp-gallery-vimeo.js"></script>
<script src="js/jquery.blueimp-gallery.js"></script>
Please note that the jQuery plugin is an optional extension and not required for
the Gallery functionality.
Browsers
blueimp Gallery has been tested with and supports the following browsers:
Desktop browsers
- Google Chrome 14.0+
- Apple Safari 4.0+
- Mozilla Firefox 4.0+
- Opera 10.0+
- Microsoft Internet Explorer 7.0+
Mobile browsers
- Apple Safari on iOS 6.0+
- Google Chrome on iOS 6.0+
- Google Chrome on Android 4.0+
- Default Browser on Android 2.3+
- Opera Mobile 12.0+
License
Released under the MIT license.
Credits
The swipe implementation is based on code from the
Swipe library.