Loading repository data…
Loading repository data…
blueimp / repository
blueimp Gallery is a touch-enabled, responsive and customizable image & 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.
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
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.
Install the blueimp-gallery package with NPM:
npm install blueimp-gallery
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>
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.
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>
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>
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.
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.
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:
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: 'src