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(document.getElementById('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 |
| 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. Pass 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. |
| 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 document.querySelector(this.s.selectWithin ).querySelectorAll(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 |
| enableTouch | boolean | true |
Enables touch 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. |
Thumbnail plugin
Plugin dependency
You need to include thumbnails 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. |
| thumbContHeight | number | 100 |
Height of the thumbnail container including padding and border |
| 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'; |
| toggleThumb | 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 your 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.2.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.js) in your document to use the following options.
| Name | type | default | description |
|---|---|---|---|
| share | boolean | true |
Enable/Disable share plugin |
| boolean | true |
Enable Facebook share. | |
| facebookDropdownText | string | Facebook |
Facebok dropdown text. |
| boolean | true |
Enable twitter share. | |
| twitterDropdownText | string | Twitter |
Twitter dropdown text |
| googlePlus | boolean | true |
Enable googlePlus share. |
| googlePlusDropdownText | string | GooglePlus |
GooglePlus dropdown text |
| boolean | true |
Enable pinterest share. | |
| pinterestDropdownText | string | Pinterest |
Pinterest dropdown text |
Rotate plugin
Plugin dependency
You need to include rotate plugin (lg-rotate.js) 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 = document.getElementById('lightgallery');
// Perform any action just before opening the gallery
lg.addEventListener('onBeforeOpen', function(e){
alert('onBeforeOpen');
}, false);
// custom event with extra parameters
// event.detail.index - index of the slide
// event.detail.fromTouch - true if slide function called via touch event or mouse drag
// event.detail.fromThumb - true if slide function called via thumbnail click
lg.addEventListener('onBeforeSlide', function(event){
console.log(event.detail.index, event.detail.fromTouch, event.detail.fromThumb);
}, false);
lightGallery(lg);
| Event Type | parameters | Description |
|---|---|---|
| onBeforeOpen.lg | Fired immediately before the start opening. | |
| onAfterOpen.lg | Fired immediately after opening the gallery. | |
| onAferAppendSlide.lg |
|
This event is fired when the slide content has been inserted into its slide container. |
| onAfterAppendSubHtml.lg |
|
This event is fired when the sub-html content (ex : title/ description) has been appended into the slide. |
| onSlideItemLoad.lg |
|
This event is fired once the image inside the slide has been completely loaded . |
| onBeforeSlide.lg |
|
fired immediately before each slide transition. |
| onAfterSlide.lg |
|
fired immediately after each slide transition. |
| onBeforePrevSlide.lg |
|
fired immediately before each "prev" slide transition |
| onBeforeNextSlide.lg |
|
fired immediately before each "next" slide transition |
| onDragstart.lg | Fired when the user starts to drag the slide | |
| onDragmove.lg | Fired periodically during the drag operation. | |
| onDragend.lg | Fired when the user has finished the drag operation | |
| onSlideClick.lg | Fired when the user clicks on the slide and does not crossed the swipeThreshold value. | |
| onBeforeClose.lg | Fired immediately before the start of the close process. | |
| onCloseAfter.lg | Fired immediately once lightgallery is closed. |
Methods
How to use methods
var el = document.getElementById('lightgallery');
lightGallery(el);
// Go to third slide
// Index starts from 0
window.lgData[el.getAttribute('lg-uid')].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 | id or class name of an object(div) which contain your sub html. |
| 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. |
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. |
| 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 |
| witterShareUrl | 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 |