lightGallery version 2 has been released. Please upgrade

# API

Lightgallery comes with a lot of options, events, and methods to customize the gallery without touching the core code. You can find both Lightgallery core options, and the built in plugin options here.

## Options

### Passing options

    $('#lightgallery').lightGallery({
        mode: 'lg-fade',
        cssEasing : 'cubic-bezier(0.25, 0, 0.25, 1)'
        ......
    });

### lightgallery core

Name | type | default | description
--- | --- | --- | ---
mode | string | `'lg-slide'` | Type of transition between images. lightGallery comes with lots of transition effects such as `'lg-slide'``'lg-fade'``'lg-zoom-in'``'lg-zoom-in-big'``'lg-zoom-out'``'lg-zoom-out-big'``'lg-zoom-out-in'``'lg-zoom-in-out'``'lg-soft-zoom'``'lg-scale-up'``'lg-slide-circular'``'lg-slide-circular-vertical'``'lg-slide-vertical'``'lg-slide-vertical-growth'``'lg-slide-skew-only'``'lg-slide-skew-only-rev'``'lg-slide-skew-only-y'``'lg-slide-skew-only-y-rev'``'lg-slide-skew'``'lg-slide-skew-rev'``'lg-slide-skew-cross'``'lg-slide-skew-cross-rev'``'lg-slide-skew-ver'``'lg-slide-skew-ver-rev'``'lg-slide-skew-ver-cross'``'lg-slide-skew-ver-cross-rev'``'lg-lollipop'``'lg-lollipop-rev'``'lg-rotate'``'lg-rotate-rev'``'lg-tube'`. You can find detaild demo here
cssEasing | string | `'ease'` | Type of easing to be used for css animations
easing | string | `'linear'` | Type of easing to be used for jquery animations
speed | number | `600` | Transition duration (in ms).
height | string | `'100%'` | Height of the gallery. ex: `'100%'` , `'300px'`
width | string | `'100%'` | Width of the gallery. ex: `'100%'` , `'300px'`
addClass | string | `''` | Add custom class for gallery, can be used to set different style for different gallery
startClass | string | `'lg-start-zoom'` | Starting animation class for the gallery.
backdropDuration | number | `150` | Lightgallery backdrop transtion duration. Do not change the value of backdrop via css.
hideBarsDelay | number | `6000` | Delay for hiding gallery controls in ms. Set 0, if you don't want to hide the controls.
useLeft | boolean | `false` | force lightgallery to use css left property instead of transform.
closable | boolean | `true` | allows clicks on dimmer to close gallery.
loop | boolean | `true` | If `false`, will disable the ability to loop back to the beginning of the gallery when on the last element.
escKey | boolean | `true` | Whether the LightGallery could be closed by pressing the "Esc" key.
keyPress | boolean | `true` | Enable keyboard navigation
controls | boolean | `true` | If `false`, prev/next buttons will not be displayed.
slideEndAnimatoin | bolean | `true` | Enable slideEnd animation
hideControlOnEnd | boolean | `false` | If `true`, prev/next button will be hidden on first/last image. `false` if `slideEndAnimatoin` or `loop` is enabled.
mousewheel | boolean | `true` | Change slide on mousewheel
getCaptionFromTitleOrAlt: | boolean | `true` | Option to get captions from alt or title tags.
appendSubHtmlTo | string | `'.lg-sub-html'` | You can specify where the sub-html should be appended. `'.lg-sub-html'` or `'.lg-item'`
subHtmlSelectorRelative | boolean | `false` | Set to true if the selector in "data-sub-html" should use the current item as its origin.
ariaLabelledby | string | `''` | aria-labelledby attribute for gallery
ariaDescribedby | string | `''` | aria-describedby attribute for gallery
preload | number | `1` | Number of preload slides. will execute only after the current slide is fully loaded. ex:// you clicked on 4th image and if preload = 1 then 3rd slide and 5th slide will be loaded in the background after the 4th slide is fully loaded.. if preload is 2 then 2nd 3rd 5th 6th slides will be preloaded
showAfterLoad | boolean | `true` | Show Content once it is fully loaded
selector | string | `''` | Custom selector property instead of just child. pass `this` to select same element ex : `.class` `#id`
selectWithin | string | `''` | By default selectror element is taken from only inside the gallery element. Instead of that you can tell lightgallery to select element within a specific element. ex : `.class` `#id` `galleryItems = $(this.s.selectWithin).find(this.s.selector);`
nextHtml | string | `''` | Custom html for next control
prevHtml | string | `''` | Custom html for prev control
index | number | `0` | Allows to set which image/video should load initially
iframeMaxWidth | string | `'100%'` | Set maximum width for iframe.
download | boolean | `true` | Enable download button. By default download url will be taken from data-src/href attribute but it supports only for modern browsers. If you want you can provide another url for download via `data-download-url`. Pass `false` in `data-download-url` if you want to hide download button for the particular slide.
counter | boolean | `true` | Whether to show total number of images and index number of currently displayed image.
appendCounterTo | string | `'.lg-toolbar'` | Where the counter should be appended
swipeThreshold | number | `50` | By setting the swipeThreshold (in px) you can set how far the user must swipe for the next/prev image.
enableDrag | boolean | `true` | Enables desktop mouse drag support
enableSwipe | boolean | `true` | Enables swipe support
dynamic | boolean | `false` | LightGallery can be instantiated and launched programmatically by setting this option to `true` and populating `dynamicEl` option (see below) with the definitions of images.
dynamicEl | array | [] | An array of objects (`src`, `iframe`, `subHtml`, `thumb`, `poster`, `responsive`, `srcset` `sizes`) representing gallery elements. See example.
supportLegacyBrowser | boolean | true | Make usage of picturefill library optional as the `srcset` is supported by all modern browsers.

### Thumbnial plugin

#### Plugin dependency

You need to include thumbnials plugin (lg-thumbnail.js) in your document to use the following options.

Name | type | default | description
--- | --- | --- | ---
thumbnail | boolean | `true` | Enable thumbnails for the gallery
animateThumb | boolean | `true` | Enable thumbnail animation.
currentPagerPosition | string | `'middle'` | Position of selected thumbnail. `'left'` or `'middle'` or `'right'`
thumbWidth | number | `100` | Width of each thumbnails.
thumbHeight | string | `'80px'` | Height of each thumbnails. Applicable only if `animateThumb` is `false`.
thumbContHeight | number | `100` | Height of the thumbnail container including padding and border. Applicable only if `animateThumb` is `true`.
thumbMargin | number | `5` | Spacing between each thumbnails
exThumbImage | string or false | `false` | If you want to use external image for thumbnail, add the path of that image inside "data-" attribute and set value of this option to the name of your custom attribute. `<-- <li data-exthumbimage="externalThumb.jpg" data-src="img/img1.jpg"></li-->` `// exThumbImage: 'data-exthumbimage';`
showThumbByDefault | boolean | true | Show/Hide thumbnails by default
toogleThumb | boolean | true | Whether to display thumbnail toggle button.
pullCaptionUp | boolean | true | Pull captions above thumbnails.
enableThumbDrag | boolean | `true` | Enables desktop mouse drag support for thumbnails.
enableThumbSwipe | boolean | `true` | Enables thumbnail touch/swipe support for touch devices
swipeThreshold | number | `50` | By setting the swipeThreshold (in px) you can set how far the user must swipe for the next/prev slide.
loadYoutubeThumbnail | boolean | `true` | You can automatically load thumbnails for youtube videos from youtube by setting loadYoutubeThumbnail true
youtubeThumbSize | number | `1` | You can specify the thumbnail size by setting respective number. Here is the detailed demo
loadVimeoThumbnail | boolean | `true` | You can automatically load thumbnails for vimeo videos from vimeo by setting loadYoutubeThumbnail true.
vimeoThumbSize | string | `'thumbnail_small'` | Thumbnail size for vimeo videos: `'thumbnail_large'` or `'thumbnail_medium'` or `'thumbnail_small'` Here is the detailed demo
loadDailymotionThumbnail | boolean | `true` | You can automatically load thumbnails for dailymotion videos from dailymotion by setting loadYoutubeThumbnail true.

youtubeThumbSize values | size | description
--- | --- | ---
`0` | 480x360 pixels | Player Background Thumbnail
`1` | 120x90 pixels | Start Thumbnail
`2` | 120x90 pixels | Middle Thumbnail
`3` | 120x90 pixels | End Thumbnail
`hqdefault` | 480x360 pixels | High Quality Thumbnail
`mqdefault` | 320x180 pixels | Medium Quality Thumbnail
`default` | 120x90 pixels | Normal Quality Thumbnail
`sddefault` | 640x480 pixels | Standard Definition Thumbnail
`maxresdefault` | 1920x1080 pixels | Maximum Resolution Thumbnail

`sddefault` and `maxresdefault` are optional. which may or may not exist.

loadVimeoThumbnail values | size | description
--- | --- | ---
`thumbnail_small` | 100x75 pixels | Samll size Thumbnail
`thumbnail_medium` | 200x150 pixels | Medium size Thumbnail
`thumbnail_large` | 640x360 pixels | Large size Thumbnail

### Autoplay plugin

#### Plugin dependency

You need to include autoplay plugin (lg-autoplay.js) in your document to use the following options.

Name | type | default | description
--- | --- | --- | ---
autoplay | boolean | `true` | Enable gallery autoplay
pause | number | `5000` | The time (in ms) between each auto transition.
progressBar | boolean | `true` | Enable autoplay progress bar
fourceAutoplay | boolean | `false` | If `false` autoplay will be stopped after first user action
autoplayControls | false | `true` | Show/hide autoplay controls.
appendAutoplayControlsTo | string | `'.lg-toolbar'` | Where the autoply controls should be appended.

### Video plugin

#### Plugin dependency

You need to include video plugin in the document to use the following options.

#### API dependency

Lightgallery require vimeo player.js to be included in the document for pausing the vimeo video. (optional)
If you are using the video plugin version <= 1.3.x, you need to include froogaloop2 instead of player.js

Name | type | default | description
--- | --- | --- | ---
videoMaxWidth | string | `'855px'` | Set limit for video maximal width.
autoplayFirstVideo | boolean | `true` | Enable/DIsable first video autoplay. Note: Autoplay has to be managed using this setting. autoplay in `PlayerParams` doens't have any effect.
youtubePlayerParams | object | `{}` | Change youtube player parameters. link : https://developers.google.com/youtube/player_parameters ex: `youtubePlayerParams: { modestbranding: 1, showinfo: 0, controls: 0 }`
vimeoPlayerParams | object | `{}` | Change vimeo player parameters. link https://developer.vimeo.com/player/embedding#universal-parameters ex: `vimeoPlayerParams: { byline : 0, portrait : 0, color : 'CCCCCC' }`
dailymotionPlayerParams | object | `{}` | Change dailymotion player parameters. link https://developer.dailymotion.com/player#player-parameters
vkPlayerParams | object | `{}` | Change vk player parameters.
videojs | boolean | `false` | Enbale videojs custom video player
videojsOptions | object | `{}` | Videojs player options

### Fullscreen plugin

#### Plugin dependency

You need to include fullscreen plugin (lg-fullscreen.js) in your document to use the following options.

Name | type | default | description
--- | --- | --- | ---
fullScreen | boolean | `true` | Enable/Disable fullscreen mode

### Pager plugin

#### Plugin dependency

You need to include pager plugin (lg-pager.js) in your document to use the following options.

Name | type | default | description
--- | --- | --- | ---
pager | boolean | `true` | Enable/Disable pager

### Zoom plugin

#### Plugin dependency

You need to include zoom plugin (lg-zoom.js) in your document to use the following options.

Name | type | default | description
--- | --- | --- | ---
zoom | boolean | `true` | Enable/Disable zoom option
scale | number | `1` | Value of zoom should be incremented/decremented
enableZoomAfter | number in ms | `50` | Some css styles will be added to the images if zoom is enabled. So it might conflict if you add some custom styles to the images such as the initial transition while opening the gallery. So you can delay adding zoom related styles to the images by changing the value of `enableZoomAfter`.
actualSize | boolean | `true` | Enable actual pixel icon.

### Hash plugin

#### Plugin dependency

You need to include hash plugin (lg-hash.js) in your document to use the following options.

Name | type | default | description
--- | --- | --- | ---
hash | boolean | `true` | Enable/Disable hash plugin
galleryId | number | `1` | Unique id for each gallery. It is mandatory when you use hash plugin for multiple galleries on the same page.

### Share plugin

#### Plugin dependency

You need to include share plugin (lg-share) in your document to use the following options.

Name | type | default | description
--- | --- | --- | ---
share | boolean | `true` | Enable/Disable share plugin
facebook | boolean | `true` | Enable Facebook share.
facebookDropdownText | string | `Facebook` | Facebok dropdown text.
twitter | boolean | `true` | Enable twitter share.
twitterDropdownText | string | `Twitter` | Twitter dropdown text
googlePlus | boolean | `true` | Enable googlePlus share.
googlePlusDropdownText | string | `GooglePlus` | GooglePlus dropdown text
pinterest | boolean | `true` | Enable pinterest share.
pinterestDropdownText | string | `Pinterest` | Pinterest dropdown text

### Rotate plugin

#### Plugin dependency

You need to include rotate plugin (lg-rotate) in your document to use the following options.

Name | type | default | description
--- | --- | --- | ---
rotate | boolean | `true` | Enable/Disable rotate option
rotateLeft | boolean | `true` | Enable rotate left.
rotateRight | boolean | `true` | Enable rotate right.
flipHorizontal | boolean | `true` | Enable flip horizontal.
flipVertical | boolean | `true` | Enable flip vertical.

## Events

### How to use lightgallery custom events

    var $lg = $('#lightgallery');

    $lg.lightGallery();

    // Perform any action just before opening the gallery
    $lg.on('onBeforeOpen.lg',function(event){
        alert('onBeforeOpen');
    });

    // custom event with extra parameters
    // index - index of the slide
    // fromTouch - true if slide function called via touch event or mouse drag
    // fromThumb - true if slide function called via thumbnail click
    $lg.on('onBeforeSlide.lg',function(event, index, fromTouch, fromThumb){
        console.log(index, fromTouch, fromThumb);
    });

Event Type | parameters | Description
--- | --- | ---
onBeforeOpen.lg | `event` - jQuery event object | Fired immediately before the start opening.
onAfterOpen.lg | `event` - jQuery event object | Fired immediately after opening the gallery.
onAferAppendSlide.lg | `event` - jQuery event object `index` - Index of the slide | This event is fired when the slide content has been inserted into its slide container.
onAfterAppendSubHtml.lg | `event` - jQuery event object `index` - Index of the slide | This event is fired when the sub-html content (ex : title/ description) has been appended into the slide.
onSlideItemLoad.lg | `event` - jQuery event object `index` - Index of the slide | This event is fired once the image inside the slide has been completely loaded .
onBeforeSlide.lg | `event` - jQuery event object `prevIndex` - Index of the previous slide `index` - Index of the slide `fromTouch` - true if slide function called via touch event or mouse drag `fromThumb` - true if slide function called via thumbnail click | fired immediately before each slide transition.
onAfterSlide.lg | `event` - jQuery event object `prevIndex` - Index of the previous slide `index` - Index of the slide `fromTouch` - true if slide function called via touch event or mouse drag `fromThumb` - true if slide function called via thumbnail click | fired immediately after each slide transition.
onBeforePrevSlide.lg | `event` - jQuery event object `index` - Index of the slide `fromTouch` - true if slide function called via touch event or mouse drag | fired immediately before each "prev" slide transition
onBeforeNextSlide.lg | `event` - jQuery event object `index` - Index of the slide `fromTouch` - true if slide function called via touch event or mouse drag | fired immediately before each "next" slide transition
onDragstart.lg | `event` - jQuery event object | Fired when the user starts to drag the slide
onDragmove.lg | `event` - jQuery event object | Fired periodically during the drag operation.
onDragend.lg | `event` - jQuery event object | Fired when the user has finished the drag operation
onSlideClick.lg | `event` - jQuery event object | Fired when the user clicks on the slide and does not crossed the swipeThreshold value.
onBeforeClose.lg | `event` - jQuery event object | Fired immediately before the start of the close process.
onCloseAfter.lg | `event` - jQuery event object | Fired immediately once lightgallery is closed.

## Methods

### How to use methods

    var $lg = $('#lightgallery');

    $lg.lightGallery();

    // Go to third slide
    // Index starts from 0
    $lg.data('lightGallery').slide(2);

Name | Parameters | Description
--- | --- | ---
slide() | `index` - index of the slide. starts from 0 | Goto specific slide.
goToNextSlide() |  | Go to next slide.
goToPrevSlide() |  | Go to previous slide.
destroy() | `true` - If you pass true as a parameter destroy method will destroy the gallery completely. If parameter is undefined or false destroy will only close the gallery and plugins instance remains with the element. | close or destroy the gallery

## Attributes

Name | Description
--- | ---
data-src | the large version of your image/video
href | the large version of your image/video
data-sub-html | HTML content (captions) which displays along with the slide. Also, accepts id or class name of an object(div) which contain your sub html. If data-sub-html is not provided captions will be taken from the `alt` or `title` attributes of the image/selector. this behavior can be controlled by updating the `getCaptionFromTitleOrAlt` setting
data-sub-html-url | url of the file which contain your sub html.
data-html | id or class name of an object(div) which contain your html. used for inserting html5 videos
data-poster | Poster image for your video
data-responsive | List of images and viewport's max width separated by comma. Ex: `img/1-375.jpg 375, img/1-480.jpg 480, img/1-757.jpg 757`. You can check the demo here
data-srcset | srcset values
data-sizes | srcset sizes
data-iframe | Set true is you want to open your url in an iframe
data-download-url | Download url for your image/video. Pass `false` if you want to hide the download button.
data-width | Actual size of the image in px. used in zoom plugin to see the actual size of the image when you doubleclick on the image.
data-facebook-share-url | Facebook share URL. Specify only if you want to provide separate share URL for the specific slide. By default, current browser URL will be taken.
data-tweet-text | Tweet text
data-twitter-share-url | Twitter share URL. Specify only if you want to provide separate share URL for the specific slide. By default, current browser URL will be taken.
data-googleplus-share-url | GooglePlus share URL. Specify only if you want to provide separate share URL for the specific slide. By default, current browser URL will be taken.
data-pinterest-share-url | Pinterest share URL. Specify only if you want to provide separate share URL for the specific slide. By default, current browser URL will be taken. Note: Pinterest requires absolute URL
data-pinterest-text | Description for Pinterest post

## Dynamic variables

Name | Description
--- | ---
src | the large version of your image/video
href | the large version of your image/video
subHtml | id or class name of an object(div) which contain your sub html.
subHtmlUrl | url of the file which contain your sub html.
html | id or class name of an object(div) which contain your html. used for inserting html5 videos
alt | alt attribute for the image displayed in the gallery
title | title attribute for the video. pass only for video slides
poster | Poster image for your video
responsive | List of images and viewport's max width separated by comma. Ex: `img/1-375.jpg 375, img/1-480.jpg 480, img/1-757.jpg 757`
srcset | srcset values
sizes | srcset sizes
iframe | Set true is you want to open your like in an iframe
downloadUrl | Download url for your image/video. Pass `false` if you want to hide the download button.
width | Actual size of the image in px. used in zoom plugin to see the actual size of the image when you doubleclick on the image.
facebookShareUrl | Facebook share URL. Specify only if you want to provide separate share URL for the specific slide. By default, current browser URL will be taken.
tweetText | Tweet text
twitterShareUrl | Twitter share URL. Specify only if you want to provide separate share URL for the specific slide. By default, current browser URL will be taken.
googleplusUhareUrl | GooglePlus share URL. Specify only if you want to provide separate share URL for the specific slide. By default, current browser URL will be taken.
pinterestShareUrl | Pinterest share URL. Specify only if you want to provide separate share URL for the specific slide. By default, current browser URL will be taken. Note: Pinterest requires absolute URL
pinterestText | Description for Pinterest post.

## Sass variables

Name | value | Description
--- | --- | ---
`$backdrop-opacity` | `1` | Gallery backdrop opacity
`$lg-toolbar-bg` | `rgba(0, 0, 0, 0.45)` | Toolbar background color
`$lg-border-radius-base` | `2px` | Base border radius for the gallery elements
`$lg-theme-highlight` | `rgb(169, 7, 7)` | Gallery highlight areas like progressbar active bg, thumbnails border..
`$lg-icon-bg` | `rgba(0, 0, 0, 0.45)` | Gallery icons background color
`$lg-icon-color` | `#999` | Gallery icons color
`$lg-counter-color` | `#e6e6e6` | Gallery counter color
`$lg-counter-font-size` | `16px` | Gallery counter font size
`$lg-next-prev-bg` | `$lg-icon-bg` | Next prev controls background color
`$lg-next-prev-color` | `$lg-icon-color` | Next prev controls icon color
`$lg-next-prev-hover-color` | `$lg-icon-hover-color` | Next prev controls icon color on hover
`$lg-progress-bar-bg` | `#333` | Progress bar background color
`$lg-progress-bar-active-bg` | `$lg-theme-highlight` | Progress bar highlight color
`$lg-progress-bar-height` | `5px` | Height of the progress bar
`$zoom-transition-duration` | `0.3s` | Image zoom animation duration..
`$lg-sub-html-bg` | `rgba(0, 0, 0, 0.45)` | Sub html container background color
`$lg-sub-html-color` | `#EEE` | Sub html color
`$lg-thumb-toggle-bg` | `#0D0A0A` | Thumbnail icon toggle icon background color
`$lg-thumb-toggle-color` | `$lg-icon-color` | Thumbnail icon toggle icon color
`$lg-thumb-toggle-hover-color` | `$lg-icon-hover-color` | Thumbnail icon toggle icon color on hover
`$lg-thumb-bg` | `#0D0A0A` | Thumbnail container background color
`$zindex-outer` | `1050` | Gallery outer div z-index
`$zindex-progressbar` | `1080` | Gallery autoplay progress bar z-index
`$zindex-controls` | `1080` | Gallery controls z-index
`$zindex-toolbar` | `1080` | Gallery toolbar z-index
`$zindex-subhtml` | `1080` | Gallery sub html container z-index
`$zindex-thumbnail` | `1080` | Gallery thumbnail container z-index
`$zindex-pager` | `1080` | Gallery pager z-index
`$zindex-playbutton` | `1080` | Video play button z-index
`$zindex-item` | `1060` | Gallery slide item z-index
`$zindex-backdrop` | `1040` | Gallery backdrop z-index