blueimp Gallery

Demo
Description
Setup
Keyboard shortcuts
Options
API
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="css/blueimp-gallery.min.css" />

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

<!-- The Gallery as lightbox dialog, should be a document body child element -->
<div
  id="blueimp-gallery"
  class="blueimp-gallery"
  aria-label="image gallery"
  aria-modal="true"
  role="dialog"
>
  <div class="slides" aria-live="polite"></div>
  <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>
</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:

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

<div
  id="blueimp-gallery"
  class="blueimp-gallery blueimp-gallery-controls"
  aria-label="image gallery"
  aria-modal="true"
  role="dialog"
>
  <!-- ... -->
</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:

<div
  id="blueimp-gallery"
  class="blueimp-gallery blueimp-gallery-contain"
  aria-label="image gallery"
  aria-modal="true"
  role="dialog"
>
  <!-- ... -->
</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:

<!-- The Gallery as inline carousel, can be positioned anywhere on the page -->
<div
  id="blueimp-gallery-carousel"
  class="blueimp-gallery blueimp-gallery-carousel"
  aria-label="image carousel"
>
  <div class="slides" aria-live="off"></div>
  <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>
</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>

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:

<div id="links">
  <a
    title="Banana"
    href="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="images/banana-75.jpg" alt="Banana" />
  </a>
  <a
    title="Apple"
    href="images/apple.png"
    data-sources='[
      {
        "type": "image/svg+xml",
        "srcset": "images/apple.svg"
      },
      {
        "type": "image/webp",
        "srcset": "images/apple.webp"
      }
    ]'
    >Apple</a
  >
</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:

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

Gallery

Install / Use

README