PHPackages                             szz/blueimp-gallery - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. szz/blueimp-gallery

ActiveLibrary

szz/blueimp-gallery
===================

blueimp Gallery is a touch-enabled, responsive and customizable image and video gallery, carousel and lightbox, optimized for both mobile and desktop web browsers.

2.33.0.x-dev(8y ago)0536MITJavaScript

Since Mar 28Pushed 8y ago1 watchersCompare

[ Source](https://github.com/szz/blueimp-gallery)[ Packagist](https://packagist.org/packages/szz/blueimp-gallery)[ Docs](https://blueimp.github.io/Gallery/)[ RSS](/packages/szz-blueimp-gallery/feed)WikiDiscussions master Synced 2mo ago

READMEChangelogDependencies (1)Versions (3)Used By (0)

blueimp Gallery
===============

[](#blueimp-gallery)

- [Demo](#demo)
- [Description](#description)
- [Setup](#setup)
    - [Lightbox setup](#lightbox-setup)
    - [Controls](#controls)
    - [Carousel setup](#carousel-setup)
- [Keyboard shortcuts](#keyboard-shortcuts)
- [Options](#options)
    - [Default options](#default-options)
    - [Event callbacks](#event-callbacks)
    - [Carousel options](#carousel-options)
    - [Indicator options](#indicator-options)
    - [Fullscreen options](#fullscreen-options)
    - [Video options](#video-options)
        - [Video factory options](#video-factory-options)
        - [YouTube options](#youtube-options)
        - [Vimeo options](#vimeo-options)
    - [Container and element options](#container-and-element-options)
    - [Property options](#property-options)
- [API](#api)
    - [Initialization](#initialization)
    - [API methods](#api-methods)
    - [Videos](#videos)
        - [HTML5 video player](#html5-video-player)
        - [Multiple video sources](#multiple-video-sources)
        - [YouTube](#youtube)
        - [Vimeo](#vimeo)
    - [Additional Gallery elements](#additional-gallery-elements)
    - [Additional content types](#additional-content-types)
        - [Example HTML text factory implementation](#example-html-text-factory-implementation)
    - [jQuery plugin](#jquery-plugin)
        - [jQuery plugin setup](#jquery-plugin-setup)
        - [HTML5 data-attributes](#html5-data-attributes)
        - [Container ids and link grouping](#container-ids-and-link-grouping)
        - [Gallery object](#gallery-object)
        - [jQuery events](#jquery-events)
- [Requirements](#requirements)
- [Browsers](#browsers)
    - [Desktop browsers](#desktop-browsers)
    - [Mobile browsers](#mobile-browsers)
- [License](#license)
- [Credits](#credits)
- [Notable forks](#notable-forks)

Demo
----

[](#demo)

[blueimp Gallery Demo](https://blueimp.github.io/Gallery/)

Description
-----------

[](#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
-----

[](#setup)

### Lightbox setup

[](#lightbox-setup)

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

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

```

```

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

```

    ‹
    ›
    ×

```

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

```

```

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:

```

```

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

```

document.getElementById('links').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);
};

```

### Controls

[](#controls)

To initialize the Gallery with visible controls, add the CSS class **blueimp-gallery-controls** to the Gallery widget:

```

    ‹
    ›
    ×

```

### Carousel setup

[](#carousel-setup)

To display the images in an inline carousel instead of a lightbox, follow the [lightbox setup](#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:

```

    ‹
    ›

```

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

```

blueimp.Gallery(
    document.getElementById('links').getElementsByTagName('a'),
    {
        container: '#blueimp-gallery-carousel',
        carousel: true
    }
);

```

Keyboard shortcuts
------------------

[](#keyboard-shortcuts)

The Gallery can be controlled with the following keyboard shortcuts:

- **Return**: Toggle controls visibility.
- **Esc**: Close the Gallery lightbox.
- **Space**: Toggle the slideshow (play/pause).
- **Left**: Move to the previous slide.
- **Right**: Move to the next slide.

Please note that setting the **carousel** option to **true** disables the keyboard shortcuts by default.

Options
-------

[](#options)

### 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:
    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):
    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 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,
    // 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
};
```

### Event callbacks

[](#event-callbacks)

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

```
var gallery = blueimp.Gallery(
    linkList,
    {
        onopen: function () {
            // Callback function executed when the Gallery is initialized.
        },
        onopened: function () {
            // Callback function executed when the Gallery has been initialized
            // and the initialization transition has been completed.
        },
        onslide: function (index, slide) {
            // Callback function executed on slide change.
        },
        onslideend: function (index, slide) {
            // Callback function executed after the slide change transition.
        },
        onslidecomplete: function (index, slide) {
            // Callback function executed on slide content load.
        },
        onclose: function () {
            // Callback function executed when the Gallery is about to be closed.
        },
        onclosed: function () {
            // Callback function executed when the Gallery has been closed
            // and the closing transition has been completed.
        }
    }
);
```

### Carousel options

[](#carousel-options)

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

```
var carouselOptions = {
    hidePageScrollbars: false,
    toggleControlsOnReturn: false,
    toggleSlideshowOnSpace: false,
    enableKeyboardNavigation: false,
    closeOnEscape: false,
    closeOnSlideClick: false,
    closeOnSwipeUpOrDown: false,
    disableScroll: false,
    startSlideshow: true
};
```

The options object passed to the Gallery function extends the default options and also those options set via **carousel** mode.

### Indicator options

[](#indicator-options)

The following are the additional default options set for the slide position indicator:

```
var indicatorOptions = {
    // 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
};
```

### Fullscreen options

[](#fullscreen-options)

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

```
var fullscreenOptions = {
    // Defines if the gallery should open in fullscreen mode:
    fullScreen: false
};
```

### Video options

[](#video-options)

#### Video factory options

[](#video-factory-options)

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

```
var videoFactoryOptions = {
    // 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'
};
```

#### YouTube options

[](#youtube-options)

Options for [YouTube](https://www.youtube.com/) videos:

```
var youTubeOptions = {
    // 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: undefined,
    // Require a click on the native YouTube player for the initial playback:
    youTubeClickToPlay: true
};
```

#### Vimeo options

[](#vimeo-options)

Options for [Vimeo](https://vimeo.com/) videos:

```
var vimeoOptions = {
    // 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
};
```

### Container and element options

[](#container-and-element-options)

The widget **container** option can be set as id string (with "#" as prefix) or element node, so the following are equivalent:

```
var options = {
    container: '#blueimp-gallery'
};
```

```
var options = {
    container: document.getElementById('blueimp-gallery')
};
```

The **slidesContainer**, **titleElement** and **indicatorContainer** options can also be defined using a tag name, which selects the first tag of this kind found inside of the widget container:

```
var options = {
    slidesContainer: 'div',
    titleElement: 'h3',
    indicatorContainer: 'ol'
};
```

It is also possible to define the container and element options with a more complex [querySelector](https://developer.mozilla.org/en-US/docs/Web/API/document.querySelector), which is supported by IE8+ and all modern web browsers.

If the helper script is replaced with [jQuery](https://jquery.com/), the container and element options can be any valid jQuery selector.

### Property options

[](#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:

```

    Banana
    Apple

```

If the links are passed as JavaScript array, it is also possible to define nested property names, by using the native JavaScript accessor syntax for the property string:

```
blueimp.Gallery(
    [
        {
            data: {urls: ['https://example.org/images/banana.jpg']}
        },
        {
            data: {urls: ['https://example.org/images/apple.jpg']}
        }
    ],
    {
        urlProperty: 'data.urls[0]'
    }
);
```

API
---

[](#api)

### Initialization

[](#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:

```
var gallery = blueimp.Gallery(links, options);
```

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

```
var gallery = blueimp.Gallery([
    'https://example.org/images/banana.jpg',
    'https://example.org/images/apple.jpg',
    'https://example.org/images/orange.jpg'
]);
```

```
var gallery = blueimp.Gallery([
    {
        title: 'Banana',
        href: 'https://example.org/images/banana.jpg',
        type: 'image/jpeg',
        thumbnail: 'https://example.org/thumbnails/banana.jpg'
    },
    {
        title: 'Apple',
        href: 'https://example.org/images/apple.jpg',
        type: 'image/jpeg',
        thumbnail: 'https://example.org/thumbnails/apple.jpg'
    }
]);
```

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](#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

[](#api-methods)

The Gallery object returned by executing the Gallery function provides the following public API methods:

```
// Return the current slide index position:
var pos = gallery.getIndex();

// Return the total number of slides:
var count = gallery.getNumber();

// Move to the previous slide:
gallery.prev();

// Move to the next slide:
gallery.next();

// Move to the given slide index with the (optional) given duraction speed in milliseconds:
gallery.slide(index, duration);

// Start an automatic slideshow with the given interval in milliseconds (optional):
gallery.play(interval);

// Stop the automatic slideshow:
gallery.pause();

// Add additional slides after Gallery initialization:
gallery.add(list);

// Close and deinitialize the Gallery:
gallery.close();
```

### Videos

[](#videos)

#### HTML5 video player

[](#html5-video-player)

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

```
blueimp.Gallery([
    {
        title: 'Fruits',
        href: 'https://example.org/videos/fruits.mp4',
        type: 'video/mp4',
        poster: 'https://example.org/images/fruits.jpg'
    },
    {
        title: 'Banana',
        href: 'https://example.org/images/banana.jpg',
        type: 'image/jpeg',
        thumbnail: 'https://example.org/thumbnails/banana.jpg'
    }
]);
```

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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video)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.

#### Multiple video sources

[](#multiple-video-sources)

To provide multiple video formats, the **sources** property of a list object can be set to an array of objects with **href** and **type** properties for each video source. The first video format in the list that the browser can play will be displayed:

```
blueimp.Gallery([
    {
        title: 'Fruits',
        type: 'video/*',
        poster: 'https://example.org/images/fruits.jpg',
        sources: [
            {
                href: 'https://example.org/videos/fruits.mp4',
                type: 'video/mp4'
            },
            {
                href: 'https://example.org/videos/fruits.ogg',
                type: 'video/ogg'
            }
        ]
    }
]);
```

It is also possible to define the video sources as data-attribute on a link element in [JSON](https://developer.mozilla.org/en-US/docs/JSON) array format:

```

    Fruits

```

#### YouTube

[](#youtube)

The Gallery can display [YouTube](https://www.youtube.com/) videos for Gallery items with a **type** of **text/html** and a **youtube** property (configurable via [YouTube options](#youtube-options)) with the YouTube video-ID:

```
blueimp.Gallery([
    {
        title: 'A 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: 'Banana',
        href: 'https://example.org/images/banana.jpg',
        type: 'image/jpeg',
        thumbnail: 'https://example.org/thumbnails/banana.jpg'
    }
]);
```

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](https://developer.mozilla.org/en-US/docs/Web/API/window.postMessage)support, which excludes IE7.

#### Vimeo

[](#vimeo)

The Gallery can display [Vimeo](https://vimeo.com/) videos for Gallery items with a **type** of **text/html** and a **vimeo** property (configurable via [Vimeo options](#vimeo-options)) with the Vimeo video-ID:

```
blueimp.Gallery([
    {
        title: 'A 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: 'Banana',
        href: 'https://example.org/images/banana.jpg',
        type: 'image/jpeg',
        thumbnail: 'https://example.org/thumbnails/banana.jpg'
    }
]);
```

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](https://developer.mozilla.org/en-US/docs/Web/API/window.postMessage)support, which excludes IE7.

### Additional Gallery elements

[](#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:

```

    ‹
    ›
    ×

```

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

```
.blueimp-gallery > .description {
  position: absolute;
  top: 30px;
  left: 15px;
  color: #fff;
  display: none;
}
.blueimp-gallery-controls > .description {
  display: block;
}
```

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

```

    Banana
    Apple

```

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

```
blueimp.Gallery(
    document.getElementById('links'),
    {
        onslide: function (index, slide) {
            var text = this.list[index].getAttribute('data-description'),
                node = this.container.find('.description');
            node.empty();
            if (text) {
                node[0].appendChild(document.createTextNode(text));
            }
        }
    }
);
```

### Additional content types

[](#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](https://en.wikipedia.org/wiki/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

[](#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](#youtube) and [Vimeo](#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](https://jquery.com/), the following example uses it for convenience.

Extend the Gallery prototype with the **textFactory** method:

```
blueimp.Gallery.prototype.textFactory = function (obj, callback) {
    var $element = $('')
            .addClass('text-content')
            .attr('title', obj.title);
    $.get(obj.href)
        .done(function (result) {
            $element.html(result);
            callback({
                type: 'load',
                target: $element[0]
            });
        })
        .fail(function () {
            callback({
                type: 'error',
                target: $element[0]
            });
        });
    return $element[0];
};
```

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

```
.blueimp-gallery > .slides > .slide > .text-content {
    overflow: auto;
    margin: 60px auto;
    padding: 0 60px;
    max-width: 920px;
    text-align: left;
}
```

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

```
blueimp.Gallery([
    {
        title: 'Noodle soup',
        href: 'https://example.org/text/noodle-soup.html',
        type: 'text/html'
    },
    {
        title: 'Tomato salad',
        href: 'https://example.org/text/tomato-salad.html',
        type: 'text/html'
    }
]);
```

### jQuery plugin

[](#jquery-plugin)

#### jQuery plugin setup

[](#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](#lightbox-setup) guide, but replace the minified Gallery script with the jQuery plugin version and include it after including [jQuery](https://jquery.com/):

```

```

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

```

```

The onclick handler from the [lightbox setup](#lightbox-setup) guide is not required and can be removed.

#### HTML5 data-attributes

[](#html5-data-attributes)

Options for the Gallery lightbox opened via the jQuery plugin can be defined as [HTML5 data-attributes](https://api.jquery.com/data/#data-html5) 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](https://api.jquery.com/filter/) and allows to remove duplicates from the list:

```

    ‹
    ›
    ×

```

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

[](#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:

```

```

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

[](#gallery-object)

The gallery object is stored via [jQuery data storage](https://api.jquery.com/category/miscellaneous/data-storage/)on the Gallery widget when the Gallery is opened and can be retrieved the following way:

```
var gallery = $('#blueimp-gallery').data('gallery');
```

This gallery object provides all methods outlined in the API methods section.

#### jQuery events

[](#jquery-events)

The jQuery plugin triggers Gallery events on the widget container, with event names equivalent to the gallery [event callbacks](#event-callbacks):

```
$('#blueimp-gallery')
    .on('open', function (event) {
        // Gallery open event handler
    })
    .on('opened', function (event) {
        // Gallery opened event handler
    })
    .on('slide', function (event, index, slide) {
        // Gallery slide event handler
    })
    .on('slideend', function (event, index, slide) {
        // Gallery slideend event handler
    })
    .on('slidecomplete', function (event, index, slide) {
        // Gallery slidecomplete event handler
    })
    .on('close', function (event) {
        // Gallery close event handler
    })
    .on('closed', function (event) {
        // Gallery closed event handler
    });
```

Requirements
------------

[](#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:

```

```

The helper script can be replaced by [jQuery](https://jquery.com/) v. 1.7+.
The fullscreen, indicator, video, youtube and vimeo source files are optional if their functionality is not required.

The [jQuery plugin](#jquery-plugin) requires [jQuery](https://jquery.com/) v. 1.7+ and the basic Gallery script, while the fullscreen, indicator, video, youtube and vimeo source files are also optional:

```

```

Please note that the jQuery plugin is an optional extension and not required for the Gallery functionality.

Browsers
--------

[](#browsers)

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

### Desktop browsers

[](#desktop-browsers)

- Google Chrome 14.0+
- Apple Safari 4.0+
- Mozilla Firefox 4.0+
- Opera 10.0+
- Microsoft Internet Explorer 7.0+
- Microsoft Edge 41.0+

*Please note:*
Microsoft Edge version 40 has a query selector bug which prevents the Gallery lightbox demo from opening the image view. This has been fixed in Microsoft Edge version 41 and later.
Thanks to Kenneth G. Chin for the information.

### Mobile browsers

[](#mobile-browsers)

- Apple Safari on iOS 6.0+
- Google Chrome on iOS 6.0+
- Google Chrome on Android 4.0+
- Default Browser on Android 2.3+
- Opera Mobile 12.0+

License
-------

[](#license)

Released under the [MIT license](https://opensource.org/licenses/MIT).

Credits
-------

[](#credits)

The swipe implementation is based on code from the [Swipe](http://swipejs.com/) library.

Notable Forks
-------------

[](#notable-forks)

- [Rollup bundled version by Khoa Nguyen](https://github.com/khoanguyen96/Gallery/tree/rewrite-js)

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity12

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 88.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

2964d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e955e6926b278f5bbf9782e8fbe4c3a3e4b560066299d8a5c93808d78eaacaf1?d=identicon)[szz](/maintainers/szz)

---

Top Contributors

[![blueimp](https://avatars.githubusercontent.com/u/244586?v=4)](https://github.com/blueimp "blueimp (148 commits)")[![SyntaxNode](https://avatars.githubusercontent.com/u/1653437?v=4)](https://github.com/SyntaxNode "SyntaxNode (3 commits)")[![smallma](https://avatars.githubusercontent.com/u/429250?v=4)](https://github.com/smallma "smallma (2 commits)")[![mariomc](https://avatars.githubusercontent.com/u/887163?v=4)](https://github.com/mariomc "mariomc (2 commits)")[![cschoenecker](https://avatars.githubusercontent.com/u/21053090?v=4)](https://github.com/cschoenecker "cschoenecker (2 commits)")[![johndalangin](https://avatars.githubusercontent.com/u/5794958?v=4)](https://github.com/johndalangin "johndalangin (1 commits)")[![mawaha](https://avatars.githubusercontent.com/u/3709219?v=4)](https://github.com/mawaha "mawaha (1 commits)")[![mnikkane](https://avatars.githubusercontent.com/u/3878821?v=4)](https://github.com/mnikkane "mnikkane (1 commits)")[![szz](https://avatars.githubusercontent.com/u/600724?v=4)](https://github.com/szz "szz (1 commits)")[![acortelyou](https://avatars.githubusercontent.com/u/1689668?v=4)](https://github.com/acortelyou "acortelyou (1 commits)")[![weberhofer](https://avatars.githubusercontent.com/u/793251?v=4)](https://github.com/weberhofer "weberhofer (1 commits)")[![ameer1234567890](https://avatars.githubusercontent.com/u/160157?v=4)](https://github.com/ameer1234567890 "ameer1234567890 (1 commits)")[![anton-staroverov](https://avatars.githubusercontent.com/u/5911853?v=4)](https://github.com/anton-staroverov "anton-staroverov (1 commits)")[![edofic](https://avatars.githubusercontent.com/u/597476?v=4)](https://github.com/edofic "edofic (1 commits)")[![iandmyhand](https://avatars.githubusercontent.com/u/2254394?v=4)](https://github.com/iandmyhand "iandmyhand (1 commits)")

### Embed Badge

![Health badge](/badges/szz-blueimp-gallery/health.svg)

```
[![Health](https://phpackages.com/badges/szz-blueimp-gallery/health.svg)](https://phpackages.com/packages/szz-blueimp-gallery)
```

###  Alternatives

[vakata/jstree

jsTree is jquery plugin, that provides interactive trees.

5.2k1.8M11](/packages/vakata-jstree)[eonasdan/bootstrap-datetimepicker

Date/time picker widget based on twitter bootstrap

7.2k492.4k9](/packages/eonasdan-bootstrap-datetimepicker)[jquery-form/form

The jQuery Form Plugin allows you to easily and unobtrusively upgrade HTML forms to use AJAX.

5.2k235.5k6](/packages/jquery-form-form)[nicolaskruchten/pivottable

Javascript Pivot Table (aka Pivot Grid, Pivot Chart, Cross-Tab) implementation with drag'n'drop.

4.4k202.9k1](/packages/nicolaskruchten-pivottable)[mottie/tablesorter

tablesorter (FORK) is a jQuery plugin for turning a standard HTML table with THEAD and TBODY tags into a sortable table without page refreshes. tablesorter can successfully parse and sort many types of data including linked data in a cell.

2.6k223.5k](/packages/mottie-tablesorter)[openmage/magento-lts

A fork of Magento-1 that is accepting bug fixes (backward compatible, drop in replacement for official Magento)

915231.1k19](/packages/openmage-magento-lts)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)