Powerful Responsive Image Gallery Plugin - Blueimp Gallery
| File Size: | 256 KB |
|---|---|
| Views Total: | 39544 |
| Last Update: | |
| Publish Date: | |
| Official Website: | Go to website |
| License: | MIT |
Blueimp Gallery is a powerful and multi-functional jQuery/Vanilla JavaScript plugin for creating responsive, touch-friendly and fully configurable image/video gallery, carousel slider and lightbox gallery on the page.
Key Features:
- Swipe, mouse and keyboard navigation.
- Cool transition effects.
- Full screen gallery lightbox mode.
- Infinite carousel slider.
- Slideshow functionality supported.
- Supports Youtube and Vimeo videos.
See also:
Basic Usage:
1. Load the Blueimp Gallery’s stylesheet file(s) in the document.
<!-- Core --> <link rel="stylesheet" href="css/blueimp-gallery.css"> <!-- Video Support --> <link rel="stylesheet" href="css/blueimp-gallery-video.css"> <!-- Nav Indicators --> <link rel="stylesheet" href="css/blueimp-gallery-indicator.css"> <!-- OR All In One + Minified --> <link rel="stylesheet" href="css/blueimp-gallery.min.css">
2. Load the Blueimp Gallery’s JavaScript files in the document.
<!-- As A Vanilla JavaScript Plugin --> <script src="js/blueimp-gallery.min.js"></script> <!-- As A jQuery Plugin --> <script src="/path/to/cdn/jquery.min.js"></script> <script src="js/blueimp-gallery.min.js"></script>
3. Create an inline carousel slider from media links as these:
<!-- Media Links -->
<div id="links">
<a href="1.jpg" title="Alt 1" data-description="Description 1 (OPTIONAL)">
<img src="thumb-1.jpg" alt="Alt 1" />
</a>
<a href="2.jpg" title="Alt 1">
<img src="thumb-1.jpg" alt="Alt 1" />
</a>
<a href="3.jpg" title="Alt 1">
<img src="thumb-1.jpg" alt="Alt 1" />
</a>
<a href="1.mp4"
title="HTML5 Video"
type="video/mp4"
data-poster="poster.jpg"
data-sources='[{"href": "1.mp4", "type": "video/mp4"}, {"href": "1.ogg", "type": "video/ogg"}]'>
HTML5 Video
</a>
</div>
<!-- Carousel Controls -->
<div id="blueimp-gallery-carousel" class="blueimp-gallery blueimp-gallery-carousel"
>
<div class="slides"></div>
<h3 class="title"></h3>
<a class="prev">‹</a>
<a class="next">›</a>
<a class="play-pause"></a>
<ol class="indicator"></ol>
</div>
blueimp.Gallery(document.getElementById('example').getElementsByTagName('a'), {
container: '#blueimp-gallery-carousel',
carousel: true
})
4. To initialize the plugin as a gallery lightbox, call the function as follows:
document.getElementById('example').onclick = function(event) {
event = event || window.event
var target = event.target || event.srcElement,
link = target.src ? target.parentNode : target,
options = { index: link, event: event },
links = this.getElementsByTagName('a')
blueimp.Gallery(links, options)
}
5. You're also allowed to define the gallery content in the JavaScript as follows:
blueimp.Gallery([
{
title: 'YouYube video',
href: 'https://www.youtube.com/watch?v=VIDEO_ID',
type: 'text/html',
youtube: 'VIDEO_ID',
poster: 'https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg'
},
{
title: 'Vimeo video',
href: 'https://vimeo.com/VIDEO_ID',
type: 'text/html',
vimeo: 'VIDEO_ID',
poster: 'https://secure-b.vimeocdn.com/ts/POSTER_ID.jpg'
},
{
title: 'HTML5 Video',
type: 'video/*',
poster: 'poster.jpg',
sources: [
{
href: '1.mp4',
type: 'video/mp4'
},
{
href: '1.ogg',
type: 'video/ogg'
}
]
}
{
title: 'Image 1',
href: '1.jpg',
type: 'image/jpeg',
thumbnail: 'thumb-1.jpg'
}
])
6. All possible options and event handlers to customize the gallery plugin.
var options = {
/* Core 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 for all slides:
slideClass: 'slide',
// 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 URL(s):
srcsetProperty: 'urlset',
// 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,
// Defines if images should be stretched to fill the available space,
// while maintaining their aspect ratio (will only be enabled for browsers
// supporting background-size="contain", which excludes IE < 9).
// Set to "cover", to make images cover all available space (requires
// support for background-size="cover", which excludes IE < 9):
stretchImages: false,
// Toggle the controls on pressing the Return key:
toggleControlsOnReturn: 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 left and right on the keyboard:
enableKeyboardNavigation: true,
// Close the gallery on pressing the Esc 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,
// 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):
carouselOptions: {
hidePageScrollbars: false,
toggleControlsOnReturn: false,
toggleSlideshowOnSpace: false,
enableKeyboardNavigation: false,
closeOnEscape: false,
closeOnSlideClick: false,
closeOnSwipeUpOrDown: false,
disableScroll: false,
startSlideshow: true
}
*/
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 speed between slide changes in milliseconds:
transitionSpeed: 400,
// The transition speed for automatic slide changes, set to an integer
// greater 0 to override the default transition speed:
slideshowTransitionSpeed: undefined,
/* Event handlers */
// 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,
/* Fullscreen mode */
// enable fullsceen mode
fullScreen: false,
/* Indicator */
// 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,
/* HTML5 Video */
// 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 list object property (or data attribute) for the video poster URL:
videoPosterProperty: 'poster',
// The list object property (or data attribute) for the video sources array:
videoSourcesProperty: 'sources',
/* Vimeo Video */
// 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:
'//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,
/* Youtube Video */
// 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: {
wmode: 'transparent'
},
// Require a click on the native YouTube player for the initial playback:
youTubeClickToPlay: true
};
7. API methods.
// back to the prev item gallery.prev(); // go to the next item gallery.next(); // go to a specific item gallery.slide(index, duration); // auto play with an interval gallery.play(interval); // pause gallery.pause(); // add new items gallery.add(list); // close the gallery gallery.close(); // get the current slide index var pos = gallery.getIndex(); // get the total number of slides var count = gallery.getNumber();
Changelog:
v2.36.0 (2019-11-05)
- Package updated.
- Doc updated.
v2.15.0 (2014-04-20)
- Automatically infer the url (and poster for YT) from the YouTube/Vimeo video ID.
v2.14.0 (2014-02-26)
- Has the ability to log Gallery initialization issues to the browser console.
v2.13.2 (2014-02-19)
- Exit FullScreen mode directly on close, as Firefox prevents asynchronous API access.
v2.13.1 (2014-02-14)
- Added wmode
v2.12.5 (2013-12-28)
- Added wmode
v2.12.4 (2013-12-13)
- Fixed vertical viewport scrolling on IE for touch devices.
- Make it easier to configure slide click events via classes.
v2.12.1 (2013-11-13)
- Display HTML5 video with 100% width & height.
v2.11.3 (2013-10-31)
- Added cover mode for the stretchImages option.
v2.11.2 (2013-10-19)
- No ".js" extension for module dependencies.
v2.11.1 (2013-10-18)
- Added hover states for the controls.
v2.10.1 (2013-10-12)
- Adjust the carousel height based on the carousel width.
v2.10.2 (2013-10-04)
- Added YouTube and Vimeo player plugins.
- Added cover mode for the stretchImages option.
- Adjust the carousel height based on the carousel width.
v2.9.0 (2013-09-20)
- Added onopened and onclosed event callback options.
v2.8.1 (2013-09-13)
- Bind the click handler to the document node to allow including the jQuery plugin in the document head.
v2.7.4 (2013-08-31)
- Fixed an error in the browser support function when the Gallery script is included in the document head.
v2.7.3 (2013-08-09)
- Enforce content-box box-sizing for the navigation and indicators.
v2.7.1 (2013-08-01)
- Fixed touch event compatibility with jQuery.
v2.7.0 (2013-07-23)
- Added event and onopen callback options.
v2.6.1 (2013-07-17)
- Fixed slide class test if options clearSlides it set to true.
- Added option unloadElements (default: true), to remove elements outside of the preload range from the DOM.
v2.5.0 (2013-07-16)
- Moved helper functions and fullscreen, indicator and video functionality into separate source files.
This awesome jQuery plugin is developed by blueimp. For more Advanced Usages, please check the demo page or visit the official website.
