`

Add the following JavaScript code after including the Gallery script to
initialize the carousel:

`html

`

$3

The Gallery supports the concept of
responsive images
with the srcset, sizes and sources object properties, e.g. using the
API:

`js
var gallery = blueimp.Gallery([
{
title: 'Banana',
href: 'https://example.org/images/banana-1024w.jpg',
srcset:
'https://example.org/images/banana-800w.jpg 800w,' +
'https://example.org/images/banana-1024w.jpg 1024w,' +
'https://example.org/images/banana-1600w.jpg 1600w',
sizes: '(min-width: 990px) 990px, 100vw',
thumbnail: 'https://example.org/images/banana-75.jpg'
},
{
title: 'Apple',
href: 'https://example.org/images/apple.png',
sources: [
{
type: 'image/svg+xml',
srcset: 'https://example.org/images/apple.svg'
},
{
type: 'image/webp',
srcset: 'https://example.org/images/apple.webp'
}
]
}
])
`

With link elements, those same properties can be defined via data-srcset,
data-sizes and data-sources attributes:

`html



`

Please note that data-sources must be a valid
JSON string listing
the sources array.

Keyboard shortcuts

The Gallery can be controlled with the following keyboard shortcuts:

- Enter: Toggle controls visibility.
- Escape: Close the Gallery lightbox.
- Space: Toggle the slideshow (play/pause).
- ArrowLeft: Move to the previous slide.
- ArrowRight: Move to the next slide.

Please note that setting the carousel option to true disables the keyboard
shortcuts by default.

Options

$3

The following are the default options set by the core Gallery library:

`js
var options = {
// The Id, element or querySelector of the gallery widget:
container: '#blueimp-gallery',
// The tag name, Id, element or querySelector of the slides container:
slidesContainer: 'div',
// The tag name, Id, element or querySelector of the title element:
titleElement: 'h3',
// The class to add when the gallery is visible:
displayClass: 'blueimp-gallery-display',
// The class to add when the gallery controls are visible:
controlsClass: 'blueimp-gallery-controls',
// The class to add when the gallery only displays one element:
singleClass: 'blueimp-gallery-single',
// The class to add when the left edge has been reached:
leftEdgeClass: 'blueimp-gallery-left',
// The class to add when the right edge has been reached:
rightEdgeClass: 'blueimp-gallery-right',
// The class to add when the automatic slideshow is active:
playingClass: 'blueimp-gallery-playing',
// The class to add when the browser supports SVG as img (or background):
svgasimgClass: 'blueimp-gallery-svgasimg',
// The class to add when the browser supports SMIL (animated SVGs):
smilClass: 'blueimp-gallery-smil',
// The class for all slides:
slideClass: 'slide',
// The slide class for the active (current index) slide:
slideActiveClass: 'slide-active',
// The slide class for the previous (before current index) slide:
slidePrevClass: 'slide-prev',
// The slide class for the next (after current index) slide:
slideNextClass: 'slide-next',
// The slide class for loading elements:
slideLoadingClass: 'slide-loading',
// The slide class for elements that failed to load:
slideErrorClass: 'slide-error',
// The class for the content element loaded into each slide:
slideContentClass: 'slide-content',
// The class for the "toggle" control:
toggleClass: 'toggle',
// The class for the "prev" control:
prevClass: 'prev',
// The class for the "next" control:
nextClass: 'next',
// The class for the "close" control:
closeClass: 'close',
// The class for the "play-pause" toggle control:
playPauseClass: 'play-pause',
// The list object property (or data attribute) with the object type:
typeProperty: 'type',
// The list object property (or data attribute) with the object title:
titleProperty: 'title',
// The list object property (or data attribute) with the object alt text:
altTextProperty: 'alt',
// The list object property (or data attribute) with the object URL:
urlProperty: 'href',
// The list object property (or data attribute) with the object srcset:
srcsetProperty: 'srcset',
// The list object property (or data attribute) with the object sizes:
sizesProperty: 'sizes',
// The list object property (or data attribute) with the object sources:
sourcesProperty: 'sources',
// The gallery listens for transitionend events before triggering the
// opened and closed events, unless the following option is set to false:
displayTransition: true,
// Defines if the gallery slides are cleared from the gallery modal,
// or reused for the next gallery initialization:
clearSlides: true,
// Toggle the controls on pressing the Enter key:
toggleControlsOnEnter: true,
// Toggle the controls on slide click:
toggleControlsOnSlideClick: true,
// Toggle the automatic slideshow interval on pressing the Space key:
toggleSlideshowOnSpace: true,
// Navigate the gallery by pressing the ArrowLeft and ArrowRight keys:
enableKeyboardNavigation: true,
// Close the gallery on pressing the Escape key:
closeOnEscape: true,
// Close the gallery when clicking on an empty slide area:
closeOnSlideClick: true,
// Close the gallery by swiping up or down:
closeOnSwipeUpOrDown: true,
// Close the gallery when the URL hash changes:
closeOnHashChange: true,
// Emulate touch events on mouse-pointer devices such as desktop browsers:
emulateTouchEvents: true,
// Stop touch events from bubbling up to ancestor elements of the Gallery:
stopTouchEventsPropagation: false,
// Hide the page scrollbars:
hidePageScrollbars: true,
// Stops any touches on the container from scrolling the page:
disableScroll: true,
// Carousel mode (shortcut for carousel specific options):
carousel: false,
// Allow continuous navigation, moving from last to first
// and from first to last slide:
continuous: true,
// Remove elements outside of the preload range from the DOM:
unloadElements: true,
// Start with the automatic slideshow:
startSlideshow: false,
// Delay in milliseconds between slides for the automatic slideshow:
slideshowInterval: 5000,
// The direction the slides are moving: ltr=LeftToRight or rtl=RightToLeft
slideshowDirection: 'ltr',
// The starting index as integer.
// Can also be an object of the given list,
// or an equal object with the same url property:
index: 0,
// The number of elements to load around the current index:
preloadRange: 2,
// The transition duration between slide changes in milliseconds:
transitionDuration: 300,
// The transition duration for automatic slide changes, set to an integer
// greater 0 to override the default transition duration:
slideshowTransitionDuration: 500,
// The event object for which the default action will be canceled
// on Gallery initialization (e.g. the click event to open the Gallery):
event: undefined,
// Callback function executed when the Gallery is initialized.
// Is called with the gallery instance as "this" object:
onopen: undefined,
// Callback function executed when the Gallery has been initialized
// and the initialization transition has been completed.
// Is called with the gallery instance as "this" object:
onopened: undefined,
// Callback function executed on slide change.
// Is called with the gallery instance as "this" object and the
// current index and slide as arguments:
onslide: undefined,
// Callback function executed after the slide change transition.
// Is called with the gallery instance as "this" object and the
// current index and slide as arguments:
onslideend: undefined,
// Callback function executed on slide content load.
// Is called with the gallery instance as "this" object and the
// slide index and slide element as arguments:
onslidecomplete: undefined,
// Callback function executed when the Gallery is about to be closed.
// Is called with the gallery instance as "this" object:
onclose: undefined,
// Callback function executed when the Gallery has been closed
// and the closing transition has been completed.
// Is called with the gallery instance as "this" object:
onclosed: undefined
}
`

$3

Event callbacks can be set as function properties of the options object passed
to the Gallery initialization function:

`js
var gallery = blueimp.Gallery(linkList, {
onopen: function () {
// Callback function executed when the Gallery is initialized.
},
onopened: function () {
// Callback function executed when the Gallery has been initialized
// and the initialization transition has been completed.
},
onslide: function (index, slide) {
// Callback function executed on slide change.
},
onslideend: function (index, slide) {
// Callback function executed after the slide change transition.
},
onslidecomplete: function (index, slide) {
// Callback function executed on slide content load.
},
onclose: function () {
// Callback function executed when the Gallery is about to be closed.
},
onclosed: function () {
// Callback function executed when the Gallery has been closed
// and the closing transition has been completed.
}
})
`

$3

If the carousel option is true, the following options are set to different
default values:

`js
var carouselOptions = {
hidePageScrollbars: false,
toggleControlsOnEnter: false,
toggleSlideshowOnSpace: false,
enableKeyboardNavigation: false,
closeOnEscape: false,
closeOnSlideClick: false,
closeOnSwipeUpOrDown: false,
closeOnHashChange: 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.

$3

The following are the additional default options set for the slide position
indicator:

`js
var indicatorOptions = {
// The tag name, Id, element or querySelector of the indicator container:
indicatorContainer: 'ol',
// The class for the active indicator:
activeIndicatorClass: 'active',
// The list object property (or data attribute) with the thumbnail URL,
// used as alternative to a thumbnail child element:
thumbnailProperty: 'thumbnail',
// Defines if the gallery indicators should display a thumbnail:
thumbnailIndicators: true
}
`

$3

The following are the additional default options set for the fullscreen mode:

`js
var fullscreenOptions = {
// Defines if the gallery should open in fullscreen mode:
fullscreen: false
}
`

$3

#### Video factory options

The following are the additional default options set for the video factory:

`js
var videoFactoryOptions = {
// The class for video content elements:
videoContentClass: 'video-content',
// The class for video when it is loading:
videoLoadingClass: 'video-loading',
// The class for video when it is playing:
videoPlayingClass: 'video-playing',
// The class for video content displayed in an iframe:
videoIframeClass: 'video-iframe',
// The class for the video cover element:
videoCoverClass: 'video-cover',
// The class for the video play control:
videoPlayClass: 'video-play',
// Play videos inline by default:
videoPlaysInline: true,
// The list object property (or data attribute) for video preload:
videoPreloadProperty: 'preload',
// The list object property (or data attribute) for the video poster URL:
videoPosterProperty: 'poster'
}
`

#### YouTube options

Options for YouTube videos:

`js
var youTubeOptions = {
// The list object property (or data attribute) with the YouTube video id:
youTubeVideoIdProperty: 'youtube',
// Optional object with parameters passed to the YouTube video player:
// https://developers.google.com/youtube/player_parameters
youTubePlayerVars: undefined,
// Require a click on the native YouTube player for the initial playback:
youTubeClickToPlay: true
}
`

#### Vimeo options

Options for Vimeo videos:

`js
var vimeoOptions = {
// The list object property (or data attribute) with the Vimeo video id:
vimeoVideoIdProperty: 'vimeo',
// The URL for the Vimeo video player, can be extended with custom parameters:
// https://developer.vimeo.com/player/embedding
vimeoPlayerUrl:
'https://player.vimeo.com/video/VIDEO_ID?api=1&player_id=PLAYER_ID',
// The prefix for the Vimeo video player ID:
vimeoPlayerIdPrefix: 'vimeo-player-',
// Require a click on the native Vimeo player for the initial playback:
vimeoClickToPlay: true
}
`

$3

The widget container, slidesContainer, titleElement and
indicatorContainer options can be set as
CSS selector
or HTMLElement node, so the following are equivalent:

`js
var options = {
container: '#blueimp-gallery'
}
`

`js
var options = {
container: document.getElementById('blueimp-gallery')
}
`

CSS selectors are passed as argument to
querySelectorAll,
which is supported by IE8+ and all modern web browsers and queried with
getElementById
or
getElementsByTagName
in older browsers.

If the helper script is replaced with jQuery, the
container and element options can be any valid jQuery selector.

$3

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:

`html



`

If the links are provided as JavaScript array, it is also possible to define
nested property names, by using the native JavaScript accessor syntax for the
property string:

`js
blueimp.Gallery(
[
{
data: { urls: ['https://example.org/images/banana.jpg'] }
},
{
data: { urls: ['https://example.org/images/apple.jpg'] }
}
],
{
urlProperty: 'data.urls[0]'
}
)
`

API

$3

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:

`js
var gallery = blueimp.Gallery(links, options)
`

The links array can be a list of URL strings or a list of objects with URL
properties:

`js
var gallery = blueimp.Gallery([
'https://example.org/images/banana.jpg',
'https://example.org/images/apple.jpg',
'https://example.org/images/orange.jpg'
])
`

`js
var gallery = blueimp.Gallery([
{
title: 'Banana',
type: 'image/jpeg',
href: 'https://example.org/images/banana.jpg',
thumbnail: 'https://example.org/thumbnails/banana.jpg'
},
{
title: 'Apple',
type: 'image/jpeg',
href: 'https://example.org/images/apple.jpg',
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.

$3

The Gallery object returned by executing the Gallery function provides the
following public API methods:

`js
// Return the current slide index position:
var pos = gallery.getIndex()

// Return the total number of slides:
var count = gallery.getNumber()

// Move to the previous slide:
gallery.prev()

// Move to the next slide:
gallery.next()

// Move to a slide index with the (optional) duration in milliseconds:
gallery.slide(index, duration)

// Start an automatic slideshow with the (optional) interval in milliseconds:
gallery.play(interval)

// Stop the automatic slideshow:
gallery.pause()

// Add additional slides after Gallery initialization:
gallery.add(list)

// Close and deinitialize the Gallery:
gallery.close()
`

$3

#### HTML5 video player

The Gallery can be initialized with a list of videos instead of images, or a
combination of both:

`js
blueimp.Gallery([
{
title: 'Fruits',
type: 'video/mp4',
href: 'https://example.org/videos/fruits.mp4',
poster: 'https://example.org/images/fruits.jpg'
},
{
title: 'Banana',
type: 'image/jpeg',
href: 'https://example.org/images/banana.jpg',
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.

#### Video controls

To start video playback, you can either click on the video play icon or on the
video slide itself.
Starting the video playback enables the native HTML5 video
controls.

To toggle the Gallery controls (previous slide, next slide, etc.) instead of
starting video playback on click of a video slide, add the toggle class to the
video cover element using the videoCoverClass Gallery option:

`js
blueimp.Gallery(
[
{
title: 'Fruits',
type: 'video/mp4',
href: 'https://example.org/videos/fruits.mp4',
poster: 'https://example.org/images/fruits.jpg'
}
],
{
videoCoverClass: 'video-cover toggle'
}
)
`

#### Video preloading

You can set the preload property of a Gallery video object to a valid value
defined by the HTML5 video
preload
attribute:

- none: Indicates that the video should not be preloaded.
- metadata: Indicates that only video metadata (e.g. length) is fetched.
- auto: Indicates that the whole video file can be preloaded.

`js
blueimp.Gallery([
{
title: 'Fruits',
type: 'video/mp4',
href: 'https://example.org/videos/fruits.mp4',
preload: 'auto'
}
])
`

By default, preload is set to none to save on network bandwidth consumption.

#### Fullscreen video

By default, videos are displayed with the HTML5 video
playsinline
attribute set, which indicates that the video is to be played inline.
To disable this behavior, you can set the Gallery option videoPlaysInline to
false:

`js
blueimp.Gallery(
[
{
title: 'Fruits',
type: 'video/mp4',
href: 'https://example.org/videos/fruits.mp4',
poster: 'https://example.org/images/fruits.jpg'
}
],
{
videoPlaysInline: false
}
)
`

Please note that this attribute only has an effect on some mobile browsers, e.g.
Safari on iOS 10 and later.
However, all browsers provide video controls to switch between fullscreen and
inline mode on user request.

#### Multiple video sources

To provide multiple video formats, the sources property of a list object can
be set to an array of objects with type and src properties for each video
source. The first video format in the list that the browser can play will be
displayed:

`js
blueimp.Gallery([
{
title: 'Fruits',
type: 'video',
sources: [
{
type: 'video/mp4',
src: 'https://example.org/videos/fruits.mp4'
},
{
type: 'video/ogg',
src: 'https://example.org/videos/fruits.ogv'
}
],
poster: 'https://example.org/images/fruits.jpg'
}
])
`

It is also possible to define the video sources as data-sources attribute as a
JSON string listing
the sources array:

`html



`

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

`js
blueimp.Gallery([
{
title: 'A YouYube video',
type: 'text/html',
href: 'https://www.youtube.com/watch?v=VIDEO_ID',
youtube: 'VIDEO_ID',
poster: 'https://img.youtube.com/vi/VIDEO_ID/maxresdefault.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:

`js
blueimp.Gallery([
{
title: 'A Vimeo video',
type: 'text/html',
href: 'https://vimeo.com/VIDEO_ID',
vimeo: 'VIDEO_ID',
poster: 'https://secure-b.vimeocdn.com/ts/POSTER_ID.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.

$3

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:

`html
id="blueimp-gallery"
class="blueimp-gallery"
aria-label="image gallery"
aria-modal="true"
role="dialog"
>


class="prev"
aria-controls="blueimp-gallery"
aria-label="previous slide"
aria-keyshortcuts="ArrowLeft"
>
class="next"
aria-controls="blueimp-gallery"
aria-label="next slide"
aria-keyshortcuts="ArrowRight"
>
class="close"
aria-controls="blueimp-gallery"
aria-label="close"
aria-keyshortcuts="Escape"
>
class="play-pause"
aria-controls="blueimp-gallery"
aria-label="play slideshow"
aria-keyshortcuts="Space"
aria-pressed="false"
role="button"
>