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:

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

<link rel="stylesheet" href="https://github.com/blueimp/Gallery/raw/v3.4.0/css/blueimp-gallery.min.css" />

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

  <h3 class="title"></h3>
  <a
    class="prev"
    aria-controls="blueimp-gallery"
    aria-label="previous slide"
    aria-keyshortcuts="ArrowLeft"
  ></a>
  <a
    class="next"
    aria-controls="blueimp-gallery"
    aria-label="next slide"
    aria-keyshortcuts="ArrowRight"
  ></a>
  <a
    class="close"
    aria-controls="blueimp-gallery"
    aria-label="close"
    aria-keyshortcuts="Escape"
  ></a>
  <a
    class="play-pause"
    aria-controls="blueimp-gallery"
    aria-label="play slideshow"
    aria-keyshortcuts="Space"
    aria-pressed="false"
    role="button"
  ></a>
  <ol class="indicator"></ol>

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:

<script src="https://github.com/blueimp/Gallery/raw/v3.4.0/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:

  <a href="https://github.com/blueimp/Gallery/raw/v3.4.0/images/banana.jpg" title="Banana">
    <img src="https://github.com/blueimp/Gallery/raw/v3.4.0/images/thumbnails/banana.jpg" alt="Banana" />
  </a>
  <a href="https://github.com/blueimp/Gallery/raw/v3.4.0/images/apple.jpg" title="Apple">
    <img src="https://github.com/blueimp/Gallery/raw/v3.4.0/images/thumbnails/apple.jpg" alt="Apple" />
  </a>
  <a href="https://github.com/blueimp/Gallery/raw/v3.4.0/images/orange.jpg" title="Orange">
    <img src="https://github.com/blueimp/Gallery/raw/v3.4.0/images/thumbnails/orange.jpg" alt="Orange" />
  </a>

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:

<script>
  document.getElementById('links').onclick = function (event) {
    event = event || window.event
    var target = event.target || event.srcElement
    var link = target.src ? target.parentNode : target
    var options = { index: link, event: event }
    var links = this.getElementsByTagName('a')
    blueimp.Gallery(links, options)
  }
</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:

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:

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:

  <h3 class="title"></h3>
  <a
    class="prev"
    aria-controls="blueimp-gallery-carousel"
    aria-label="previous slide"
  ></a>
  <a
    class="next"
    aria-controls="blueimp-gallery-carousel"
    aria-label="next slide"
  ></a>
  <a
    class="play-pause"
    aria-controls="blueimp-gallery-carousel"
    aria-label="play slideshow"
    aria-pressed="true"
    role="button"
  ></a>
  <ol class="indicator"></ol>

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>

Responsive images

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

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:

  <a
    title="Banana"
    href="https://github.com/blueimp/Gallery/raw/v3.4.0/images/banana-1024w.jpg"
    data-srcset="images/banana-800w.jpg 800w,
                 images/banana-1024w.jpg 1024w,
                 images/banana-1600w.jpg 1600w"
    data-sizes="(min-width: 990px) 990px, 100vw"
  >
    <img src="https://github.com/blueimp/Gallery/raw/v3.4.0/images/banana-75.jpg" alt="Banana" />
  </a>
  <a
    title="Apple"
    href="https://github.com/blueimp/Gallery/raw/v3.4.0/images/apple.png"
    data-sources='[
      {
        "type": "image/svg+xml",
        "srcset": "images/apple.svg"
      },
      {
        "type": "image/webp",
        "srcset": "images/apple.webp"
      }
    ]'
    >Apple</a
  >

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:

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