blueimp Gallery

Contents

• Demo
• Description
• Setup
  • Lightbox setup
  • Controls
  • Contain
  • Carousel setup
  • Responsive images
• Keyboard shortcuts
• Options
  • Default options
  • Event callbacks
  • Carousel options
  • Indicator options
  • Fullscreen options
  • Video options
    • Video factory options
    • YouTube options
    • Vimeo options
  • Container and element options
  • Property options
• API
  • Initialization
  • API methods
  • Videos
    • HTML5 video player
    • Video controls
    • Video preloading
    • Fullscreen video
    • Multiple video sources
    • YouTube
    • Vimeo
  • Additional Gallery elements
  • Additional content types
    • Example HTML text factory implementation
  • jQuery plugin
    • jQuery plugin setup
    • HTML5 data-attributes
    • Container ids and link grouping
    • Gallery object
    • jQuery events
• Requirements
• Browser support
• License
• Credits

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

Install the blueimp-gallery package with NPM:

1npm install blueimp-gallery

Lightbox setup

Copy the css, img and js directories to your website.

Include the Gallery stylesheet in the head section of your webpage:

1<link rel="stylesheet" href="css/blueimp-gallery.min.css" />

Add the following HTML snippet with the Gallery widget to the body of your webpage:

1<!-- The Gallery as lightbox dialog, should be a document body child element -->
2<div
3  id="blueimp-gallery"
4  class="blueimp-gallery"
5  aria-label="image gallery"
6  aria-modal="true"
7  role="dialog"
8>
9  <div class="slides" aria-live="polite"></div>
10  <h3 class="title"></h3>
11  <a
12    class="prev"
13    aria-controls="blueimp-gallery"
14    aria-label="previous slide"
15    aria-keyshortcuts="ArrowLeft"
16  ></a>
17  <a
18    class="next"
19    aria-controls="blueimp-gallery"
20    aria-label="next slide"
21    aria-keyshortcuts="ArrowRight"
22  ></a>
23  <a
24    class="close"
25    aria-controls="blueimp-gallery"
26    aria-label="close"
27    aria-keyshortcuts="Escape"
28  ></a>
29  <a
30    class="play-pause"
31    aria-controls="blueimp-gallery"
32    aria-label="play slideshow"
33    aria-keyshortcuts="Space"
34    aria-pressed="false"
35    role="button"
36  ></a>
37  <ol class="indicator"></ol>
38</div>

Please note that each aria-controls attribute should have the same value as the id attribute of the Gallery widget.

Include the Gallery script at the bottom of the body of your webpage:

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

1<div id="links">
2  <a href="images/banana.jpg" title="Banana">
3    <img src="images/thumbnails/banana.jpg" alt="Banana" />
4  </a>
5  <a href="images/apple.jpg" title="Apple">
6    <img src="images/thumbnails/apple.jpg" alt="Apple" />
7  </a>
8  <a href="images/orange.jpg" title="Orange">
9    <img src="images/thumbnails/orange.jpg" alt="Orange" />
10  </a>
11</div>

Add the following JavaScript code after including the Gallery script, to display the images in the Gallery lightbox on click of one of those links:

1<script>
2  document.getElementById('links').onclick = function (event) {
3    event = event || window.event
4    var target = event.target || event.srcElement
5    var link = target.src ? target.parentNode : target
6    var options = { index: link, event: event }
7    var links = this.getElementsByTagName('a')
8    blueimp.Gallery(links, options)
9  }
10</script>

Controls

To initialize the Gallery with visible controls (previous slide, next slide, etc.), add the CSS class blueimp-gallery-controls to the Gallery widget:

1<div
2  id="blueimp-gallery"
3  class="blueimp-gallery blueimp-gallery-controls"
4  aria-label="image gallery"
5  aria-modal="true"
6  role="dialog"
7>
8  <!-- ... -->
9</div>

Please also note that by default, a click on an image slide or any Gallery widget element with the toggle class will toggle the display of the Gallery controls.

Contain

To stretch smaller images to the dimensions of the Gallery container while keeping their aspect ratio, add the CSS class blueimp-gallery-contain to the Gallery widget:

1<div
2  id="blueimp-gallery"
3  class="blueimp-gallery blueimp-gallery-contain"
4  aria-label="image gallery"
5  aria-modal="true"
6  role="dialog"
7>
8  <!-- ... -->
9</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:

1<!-- The Gallery as inline carousel, can be positioned anywhere on the page -->
2<div
3  id="blueimp-gallery-carousel"
4  class="blueimp-gallery blueimp-gallery-carousel"
5  aria-label="image carousel"
6>
7  <div class="slides" aria-live="off"></div>
8  <h3 class="title"></h3>
9  <a
10    class="prev"
11    aria-controls="blueimp-gallery-carousel"
12    aria-label="previous slide"
13  ></a>
14  <a
15    class="next"
16    aria-controls="blueimp-gallery-carousel"
17    aria-label="next slide"
18  ></a>
19  <a
20    class="play-pause"
21    aria-controls="blueimp-gallery-carousel"
22    aria-label="play slideshow"
23    aria-pressed="true"
24    role="button"
25  ></a>
26  <ol class="indicator"></ol>
27</div>

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

1<script>
2  blueimp.Gallery(document.getElementById('links').getElementsByTagName('a'), {
3    container: '#blueimp-gallery-carousel',
4    carousel: true
5  })
6</script>

Responsive images

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

1var gallery = blueimp.Gallery([
2  {
3    title: 'Banana',
4    href: 'https://example.org/images/banana-1024w.jpg',
5    srcset:
6      'https://example.org/images/banana-800w.jpg 800w,' +
7      'https://example.org/images/banana-1024w.jpg 1024w,' +
8      'https://example.org/images/banana-1600w.jpg 1600w',
9    sizes: '(min-width: 990px) 990px, 100vw',
10    thumbnail: 'https://example.org/images/banana-75.jpg'
11  },
12  {
13    title: 'Apple',
14    href: 'https://example.org/images/apple.png',
15    sources: [
16      {
17        type: 'image/svg+xml',
18        srcset: 'https://example.org/images/apple.svg'
19      },
20      {
21        type: 'image/webp',
22        srcset: 'https://example.org/images/apple.webp'
23      }
24    ]
25  }
26])

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

1<div id="links">
2  <a
3    title="Banana"
4    href="images/banana-1024w.jpg"
5    data-srcset="images/banana-800w.jpg 800w,
6                 images/banana-1024w.jpg 1024w,
7                 images/banana-1600w.jpg 1600w"
8    data-sizes="(min-width: 990px) 990px, 100vw"
9  >
10    <img src="images/banana-75.jpg" alt="Banana" />
11  </a>
12  <a
13    title="Apple"
14    href="images/apple.png"
15    data-sources='[
16      {
17        "type": "image/svg+xml",
18        "srcset": "images/apple.svg"
19      },
20      {
21        "type": "image/webp",
22        "srcset": "images/apple.webp"
23      }
24    ]'
25    >Apple</a
26  >
27</div>

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

Default options

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

1var options = {
2  // The Id, element or querySelector of the gallery widget:
3  container: '#blueimp-gallery',
4  // The tag name, Id, element or querySelector of the slides container:
5  slidesContainer: 'div',
6  // The tag name, Id, element or querySelector of the title element:
7  titleElement: 'h3',
8  // The class to add when the gallery is visible:
9  displayClass: 'blueimp-gallery-display',
10  // The class to add when the gallery controls are visible:
11  controlsClass: 'blueimp-gallery-controls',
12  // The class to add when the gallery only displays one element:
13  singleClass: 'blueimp-gallery-single',
14  // The class to add when the left edge has been reached:
15  leftEdgeClass: 'blueimp-gallery-left',
16  // The class to add when the right edge has been reached:
17  rightEdgeClass: 'blueimp-gallery-right',
18  // The class to add when the automatic slideshow is active:
19  playingClass: 'blueimp-gallery-playing',
20  // The class to add when the browser supports SVG as img (or background):
21  svgasimgClass: 'blueimp-gallery-svgasimg',
22  // The class to add when the browser supports SMIL (animated SVGs):
23  smilClass: 'blueimp-gallery-smil',
24  // The class for all slides:
25  slideClass: 'slide',
26  // The slide class for the active (current index) slide:
27  slideActiveClass: 'slide-active',
28  // The slide class for the previous (before current index) slide:
29  slidePrevClass: 'slide-prev',
30  // The slide class for the next (after current index) slide:
31  slideNextClass: 'slide-next',
32  // The slide class for loading elements:
33  slideLoadingClass: 'slide-loading',
34  // The slide class for elements that failed to load:
35  slideErrorClass: 'slide-error',
36  // The class for the content element loaded into each slide:
37  slideContentClass: 'slide-content',
38  // The class for the "toggle" control:
39  toggleClass: 'toggle',
40  // The class for the "prev" control:
41  prevClass: 'prev',
42  // The class for the "next" control:
43  nextClass: 'next',
44  // The class for the "close" control:
45  closeClass: 'close',
46  // The class for the "play-pause" toggle control:
47  playPauseClass: 'play-pause',
48  // The list object property (or data attribute) with the object type:
49  typeProperty: 'type',
50  // The list object property (or data attribute) with the object title:
51  titleProperty: 'title',
52  // The list object property (or data attribute) with the object alt text:
53  altTextProperty: 'alt',
54  // The list object property (or data attribute) with the object URL:
55  urlProperty: 'href',
56  // The list object property (or data attribute) with the object srcset:
57  srcsetProperty: 'srcset',
58  // The list object property (or data attribute) with the object sizes:
59  sizesProperty: 'sizes',
60  // The list object property (or data attribute) with the object sources:
61  sourcesProperty: 'sources',
62  // The gallery listens for transitionend events before triggering the
63  // opened and closed events, unless the following option is set to false:
64  displayTransition: true,
65  // Defines if the gallery slides are cleared from the gallery modal,
66  // or reused for the next gallery initialization:
67  clearSlides: true,
68  // Toggle the controls on pressing the Enter key:
69  toggleControlsOnEnter: true,
70  // Toggle the controls on slide click:
71  toggleControlsOnSlideClick: true,
72  // Toggle the automatic slideshow interval on pressing the Space key:
73  toggleSlideshowOnSpace: true,
74  // Navigate the gallery by pressing the ArrowLeft and ArrowRight keys:
75  enableKeyboardNavigation: true,
76  // Close the gallery on pressing the Escape key:
77  closeOnEscape: true,
78  // Close the gallery when clicking on an empty slide area:
79  closeOnSlideClick: true,
80  // Close the gallery by swiping up or down:
81  closeOnSwipeUpOrDown: true,
82  // Close the gallery when the URL hash changes:
83  closeOnHashChange: true,
84  // Emulate touch events on mouse-pointer devices such as desktop browsers:
85  emulateTouchEvents: true,
86  // Stop touch events from bubbling up to ancestor elements of the Gallery:
87  stopTouchEventsPropagation: false,
88  // Hide the page scrollbars:
89  hidePageScrollbars: true,
90  // Stops any touches on the container from scrolling the page:
91  disableScroll: true,
92  // Carousel mode (shortcut for carousel specific options):
93  carousel: false,
94  // Allow continuous navigation, moving from last to first
95  // and from first to last slide:
96  continuous: true,
97  // Remove elements outside of the preload range from the DOM:
98  unloadElements: true,
99  // Start with the automatic slideshow:
100  startSlideshow: false,
101  // Delay in milliseconds between slides for the automatic slideshow:
102  slideshowInterval: 5000,
103  // The direction the slides are moving: ltr=LeftToRight or rtl=RightToLeft
104  slideshowDirection: 'ltr',
105  // The starting index as integer.
106  // Can also be an object of the given list,
107  // or an equal object with the same url property:
108  index: 0,
109  // The number of elements to load around the current index:
110  preloadRange: 2,
111  // The transition duration between slide changes in milliseconds:
112  transitionDuration: 300,
113  // The transition duration for automatic slide changes, set to an integer
114  // greater 0 to override the default transition duration:
115  slideshowTransitionDuration: 500,
116  // The event object for which the default action will be canceled
117  // on Gallery initialization (e.g. the click event to open the Gallery):
118  event: undefined,
119  // Callback function executed when the Gallery is initialized.
120  // Is called with the gallery instance as "this" object:
121  onopen: undefined,
122  // Callback function executed when the Gallery has been initialized
123  // and the initialization transition has been completed.
124  // Is called with the gallery instance as "this" object:
125  onopened: undefined,
126  // Callback function executed on slide change.
127  // Is called with the gallery instance as "this" object and the
128  // current index and slide as arguments:
129  onslide: undefined,
130  // Callback function executed after the slide change transition.
131  // Is called with the gallery instance as "this" object and the
132  // current index and slide as arguments:
133  onslideend: undefined,
134  // Callback function executed on slide content load.
135  // Is called with the gallery instance as "this" object and the
136  // slide index and slide element as arguments:
137  onslidecomplete: undefined,
138  // Callback function executed when the Gallery is about to be closed.
139  // Is called with the gallery instance as "this" object:
140  onclose: undefined,
141  // Callback function executed when the Gallery has been closed
142  // and the closing transition has been completed.
143  // Is called with the gallery instance as "this" object:
144  onclosed: undefined
145}

Event callbacks

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

1var gallery = blueimp.Gallery(linkList, {
2  onopen: function () {
3    // Callback function executed when the Gallery is initialized.
4  },
5  onopened: function () {
6    // Callback function executed when the Gallery has been initialized
7    // and the initialization transition has been completed.
8  },
9  onslide: function (index, slide) {
10    // Callback function executed on slide change.
11  },
12  onslideend: function (index, slide) {
13    // Callback function executed after the slide change transition.
14  },
15  onslidecomplete: function (index, slide) {
16    // Callback function executed on slide content load.
17  },
18  onclose: function () {
19    // Callback function executed when the Gallery is about to be closed.
20  },
21  onclosed: function () {
22    // Callback function executed when the Gallery has been closed
23    // and the closing transition has been completed.
24  }
25})

Carousel options

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

1var carouselOptions = {
2  hidePageScrollbars: false,
3  toggleControlsOnEnter: false,
4  toggleSlideshowOnSpace: false,
5  enableKeyboardNavigation: false,
6  closeOnEscape: false,
7  closeOnSlideClick: false,
8  closeOnSwipeUpOrDown: false,
9  closeOnHashChange: false,
10  disableScroll: false,
11  startSlideshow: true
12}

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:

1var indicatorOptions = {
2  // The tag name, Id, element or querySelector of the indicator container:
3  indicatorContainer: 'ol',
4  // The class for the active indicator:
5  activeIndicatorClass: 'active',
6  // The list object property (or data attribute) with the thumbnail URL,
7  // used as alternative to a thumbnail child element:
8  thumbnailProperty: 'thumbnail',
9  // Defines if the gallery indicators should display a thumbnail:
10  thumbnailIndicators: true
11}

Fullscreen options

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

1var fullscreenOptions = {
2  // Defines if the gallery should open in fullscreen mode:
3  fullscreen: false
4}

Video options

Video factory options

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

1var videoFactoryOptions = {
2  // The class for video content elements:
3  videoContentClass: 'video-content',
4  // The class for video when it is loading:
5  videoLoadingClass: 'video-loading',
6  // The class for video when it is playing:
7  videoPlayingClass: 'video-playing',
8  // The class for video content displayed in an iframe:
9  videoIframeClass: 'video-iframe',
10  // The class for the video cover element:
11  videoCoverClass: 'video-cover',
12  // The class for the video play control:
13  videoPlayClass: 'video-play',
14  // Play videos inline by default:
15  videoPlaysInline: true,
16  // The list object property (or data attribute) for video preload:
17  videoPreloadProperty: 'preload',
18  // The list object property (or data attribute) for the video poster URL:
19  videoPosterProperty: 'poster'
20}

YouTube options

Options for YouTube videos:

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

Vimeo options

Options for Vimeo videos:

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

Container and element options

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

1var options = {
2  container: '#blueimp-gallery'
3}

1var options = {
2  container: document.getElementById('blueimp-gallery')
3}

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.

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:

1<div id="links">
2  <a href="images/banana.jpg">Banana</a>
3  <a data-href="images/apple.jpg">Apple</a>
4</div>

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:

1blueimp.Gallery(
2  [
3    {
4      data: { urls: ['https://example.org/images/banana.jpg'] }
5    },
6    {
7      data: { urls: ['https://example.org/images/apple.jpg'] }
8    }
9  ],
10  {
11    urlProperty: 'data.urls[0]'
12  }
13)

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:

1var gallery = blueimp.Gallery(links, options)

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

1var gallery = blueimp.Gallery([
2  'https://example.org/images/banana.jpg',
3  'https://example.org/images/apple.jpg',
4  'https://example.org/images/orange.jpg'
5])

1var gallery = blueimp.Gallery([
2  {
3    title: 'Banana',
4    type: 'image/jpeg',
5    href: 'https://example.org/images/banana.jpg',
6    thumbnail: 'https://example.org/thumbnails/banana.jpg'
7  },
8  {
9    title: 'Apple',
10    type: 'image/jpeg',
11    href: 'https://example.org/images/apple.jpg',
12    thumbnail: 'https://example.org/thumbnails/apple.jpg'
13  }
14])

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:

1// Return the current slide index position:
2var pos = gallery.getIndex()
3
4// Return the total number of slides:
5var count = gallery.getNumber()
6
7// Move to the previous slide:
8gallery.prev()
9
10// Move to the next slide:
11gallery.next()
12
13// Move to a slide index with the (optional) duration in milliseconds:
14gallery.slide(index, duration)
15
16// Start an automatic slideshow with the (optional) interval in milliseconds:
17gallery.play(interval)
18
19// Stop the automatic slideshow:
20gallery.pause()
21
22// Add additional slides after Gallery initialization:
23gallery.add(list)
24
25// Close and deinitialize the Gallery:
26gallery.close()

Videos

HTML5 video player

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

1blueimp.Gallery([
2  {
3    title: 'Fruits',
4    type: 'video/mp4',
5    href: 'https://example.org/videos/fruits.mp4',
6    poster: 'https://example.org/images/fruits.jpg'
7  },
8  {
9    title: 'Banana',
10    type: 'image/jpeg',
11    href: 'https://example.org/images/banana.jpg',
12    thumbnail: 'https://example.org/thumbnails/banana.jpg'
13  }
14])

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:

1blueimp.Gallery(
2  [
3    {
4      title: 'Fruits',
5      type: 'video/mp4',
6      href: 'https://example.org/videos/fruits.mp4',
7      poster: 'https://example.org/images/fruits.jpg'
8    }
9  ],
10  {
11    videoCoverClass: 'video-cover toggle'
12  }
13)

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.

1blueimp.Gallery([
2  {
3    title: 'Fruits',
4    type: 'video/mp4',
5    href: 'https://example.org/videos/fruits.mp4',
6    preload: 'auto'
7  }
8])

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:

1blueimp.Gallery(
2  [
3    {
4      title: 'Fruits',
5      type: 'video/mp4',
6      href: 'https://example.org/videos/fruits.mp4',
7      poster: 'https://example.org/images/fruits.jpg'
8    }
9  ],
10  {
11    videoPlaysInline: false
12  }
13)

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:

1blueimp.Gallery([
2  {
3    title: 'Fruits',
4    type: 'video',
5    sources: [
6      {
7        type: 'video/mp4',
8        src: 'https://example.org/videos/fruits.mp4'
9      },
10      {
11        type: 'video/ogg',
12        src: 'https://example.org/videos/fruits.ogv'
13      }
14    ],
15    poster: 'https://example.org/images/fruits.jpg'
16  }
17])

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

1<div id="links">
2  <a
3    title="Fruits"
4    type="video/mp4"
5    href="https://example.org/videos/fruits.mp4"
6    data-sources='[
7      {
8        "type": "video/mp4",
9        "src": "videos/fruits.mp4"
10      },
11      {
12        "type": "video/ogg",
13        "src": "videos/fruits.ogv"
14      }
15    ]'
16    data-poster="https://example.org/images/fruits.jpg"
17    >Fruits</a
18  >
19</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:

1blueimp.Gallery([
2  {
3    title: 'A YouYube video',
4    type: 'text/html',
5    href: 'https://www.youtube.com/watch?v=VIDEO_ID',
6    youtube: 'VIDEO_ID',
7    poster: 'https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg'
8  }
9])

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:

1blueimp.Gallery([
2  {
3    title: 'A Vimeo video',
4    type: 'text/html',
5    href: 'https://vimeo.com/VIDEO_ID',
6    vimeo: 'VIDEO_ID',
7    poster: 'https://secure-b.vimeocdn.com/ts/POSTER_ID.jpg'
8  }
9])

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:

1<div
2  id="blueimp-gallery"
3  class="blueimp-gallery"
4  aria-label="image gallery"
5  aria-modal="true"
6  role="dialog"
7>
8  <div class="slides" aria-live="polite"></div>
9  <h3 class="title"></h3>
10  <!-- The placeholder for the description label: -->
11  <p class="description"></p>
12  <a
13    class="prev"
14    aria-controls="blueimp-gallery"
15    aria-label="previous slide"
16    aria-keyshortcuts="ArrowLeft"
17  ></a>
18  <a
19    class="next"
20    aria-controls="blueimp-gallery"
21    aria-label="next slide"
22    aria-keyshortcuts="ArrowRight"
23  ></a>
24  <a
25    class="close"
26    aria-controls="blueimp-gallery"
27    aria-label="close"
28    aria-keyshortcuts="Escape"
29  ></a>
30  <a
31    class="play-pause"
32    aria-controls="blueimp-gallery"
33    aria-label="play slideshow"
34    aria-keyshortcuts="Space"
35    aria-pressed="false"
36    role="button"
37  ></a>
38  <ol class="indicator"></ol>
39</div>

Next, add the desired element styles to your CSS file:

1.blueimp-gallery > .description {
2  position: absolute;
3  top: 30px;
4  left: 15px;
5  color: #fff;
6  display: none;
7}
8.blueimp-gallery-controls > .description {
9  display: block;
10}

Then, add the additional element information to each of your links:

1<div id="links">
2  <a
3    href="images/banana.jpg"
4    title="Banana"
5    data-description="This is a banana."
6    >Banana</a
7  >
8  <a href="images/apple.jpg" title="Apple" data-description="This is an apple."
9    >Apple</a
10  >
11</div>

Finally, initialize the Gallery with an onslide callback option, to set the element content based on the information from the current link:

1blueimp.Gallery(document.getElementById('links'), {
2  onslide: function (index, slide) {
3    var text = this.list[index].getAttribute('data-description'),
4      node = this.container.find('.description')
5    node.empty()
6    if (text) {
7      node[0].appendChild(document.createTextNode(text))
8    }
9  }
10})

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:

1blueimp.Gallery.prototype.textFactory = function (obj, callback) {
2  var $element = $('<div>').addClass('text-content').attr('title', obj.title)
3  $.get(obj.href)
4    .done(function (result) {
5      $element.html(result)
6      callback({
7        type: 'load',
8        target: $element[0]
9      })
10    })
11    .fail(function () {
12      callback({
13        type: 'error',
14        target: $element[0]
15      })
16    })
17  return $element[0]
18}

Next, add the text-content class to the Gallery CSS:

1.blueimp-gallery > .slides > .slide > .text-content {
2  overflow: auto;
3  margin: 60px auto;
4  padding: 0 60px;
5  max-width: 920px;
6  text-align: left;
7}

With the previous changes in place, the Gallery can now handle HTML content types:

1blueimp.Gallery([
2  {
3    title: 'Noodle soup',
4    type: 'text/html',
5    href: 'https://example.org/text/noodle-soup.html'
6  },
7  {
8    title: 'Tomato salad',
9    type: 'text/html',
10    href: 'https://example.org/text/tomato-salad.html'
11  }
12])

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:

1<script
2  src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"
3  integrity="sha384-nvAa0+6Qg9clwYCGGPpDQLVpLNn0fRaROjHqs13t4Ggj3Ez50XnGQqc/r8MhnRDZ"
4  crossorigin="anonymous"
5></script>
6<script src="js/jquery.blueimp-gallery.min.js"></script>

Next, add the attribute data-gallery to your Gallery links:

1<div id="links">
2  <a href="images/banana.jpg" title="Banana" data-gallery>
3    <img src="images/thumbnails/banana.jpg" alt="Banana" />
4  </a>
5  <a href="images/apple.jpg" title="Apple" data-gallery>
6    <img src="images/thumbnails/apple.jpg" alt="Apple" />
7  </a>
8  <a href="images/orange.jpg" title="Orange" data-gallery>
9    <img src="images/thumbnails/orange.jpg" alt="Orange" />
10  </a>
11</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:

1<div
2  id="blueimp-gallery"
3  class="blueimp-gallery"
4  aria-label="image gallery"
5  aria-modal="true"
6  role="dialog"
7  data-start-slideshow="true"
8  data-filter=":even"
9>
10  <div class="slides" aria-live="off"></div>
11  <h3 class="title"></h3>
12  <a
13    class="prev"
14    aria-controls="blueimp-gallery"
15    aria-label="previous slide"
16    aria-keyshortcuts="ArrowLeft"
17  ></a>
18  <a
19    class="next"
20    aria-controls="blueimp-gallery"
21    aria-label="next slide"
22    aria-keyshortcuts="ArrowRight"
23  ></a>
24  <a
25    class="close"
26    aria-controls="blueimp-gallery"
27    aria-label="close"
28    aria-keyshortcuts="Escape"
29  ></a>
30  <a
31    class="play-pause"
32    aria-controls="blueimp-gallery"
33    aria-label="play slideshow"
34    aria-keyshortcuts="Space"
35    aria-pressed="true"
36    role="button"
37  ></a>
38  <ol class="indicator"></ol>
39</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:

1<div id="fruits">
2  <a
3    href="images/banana.jpg"
4    title="Banana"
5    data-gallery="#blueimp-gallery-fruits"
6  >
7    <img src="images/thumbnails/banana.jpg" alt="Banana" />
8  </a>
9  <a
10    href="images/apple.jpg"
11    title="Apple"
12    data-gallery="#blueimp-gallery-fruits"
13  >
14    <img src="images/thumbnails/apple.jpg" alt="Apple" />
15  </a>
16</div>
17<div id="vegetables">
18  <a
19    href="images/tomato.jpg"
20    title="Tomato"
21    data-gallery="#blueimp-gallery-vegetables"
22  >
23    <img src="images/thumbnails/tomato.jpg" alt="Tomato" />
24  </a>
25  <a
26    href="images/onion.jpg"
27    title="Onion"
28    data-gallery="#blueimp-gallery-vegetables"
29  >
30    <img src="images/thumbnails/onion.jpg" alt="Onion" />
31  </a>
32</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:

1var 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:

1$('#blueimp-gallery')
2  .on('open', function (event) {
3    // Gallery open event handler
4  })
5  .on('opened', function (event) {
6    // Gallery opened event handler
7  })
8  .on('slide', function (event, index, slide) {
9    // Gallery slide event handler
10  })
11  .on('slideend', function (event, index, slide) {
12    // Gallery slideend event handler
13  })
14  .on('slidecomplete', function (event, index, slide) {
15    // Gallery slidecomplete event handler
16  })
17  .on('close', function (event) {
18    // Gallery close event handler
19  })
20  .on('closed', function (event) {
21    // Gallery closed event handler
22  })

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:

1<link rel="stylesheet" href="css/blueimp-gallery.css" />
2<link rel="stylesheet" href="css/blueimp-gallery-indicator.css" />
3<link rel="stylesheet" href="css/blueimp-gallery-video.css" />
4<!-- ... -->
5<script src="js/blueimp-helper.js"></script>
6<script src="js/blueimp-gallery.js"></script>
7<script src="js/blueimp-gallery-fullscreen.js"></script>
8<script src="js/blueimp-gallery-indicator.js"></script>
9<script src="js/blueimp-gallery-video.js"></script>
10<script src="js/blueimp-gallery-youtube.js"></script>
11<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:

1<script
2  src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"
3  integrity="sha384-nvAa0+6Qg9clwYCGGPpDQLVpLNn0fRaROjHqs13t4Ggj3Ez50XnGQqc/r8MhnRDZ"
4  crossorigin="anonymous"
5></script>
6<script src="js/blueimp-gallery.js"></script>
7<script src="js/blueimp-gallery-fullscreen.js"></script>
8<script src="js/blueimp-gallery-indicator.js"></script>
9<script src="js/blueimp-gallery-video.js"></script>
10<script src="js/blueimp-gallery-youtube.js"></script>
11<script src="js/blueimp-gallery-vimeo.js"></script>
12<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.

Browser support

blueimp Gallery has been tested with and supports the following browsers:

• Chrome 14.0+
• Safari 4.0+
• Firefox 4.0+
• Opera 10.0+
• Mobile Safari 6.0+
• Mobile Chrome 30.0+
• Default Browser on Android 2.3+
• Opera Mobile 12.0+
• Edge 74+
• Edge Legacy 41.0+
• Internet Explorer 7.0+

License

Released under the MIT license.

Credits

The swipe implementation is based on code from the Swipe library.