Settings

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

Passing settings

lightGallery accepts two parameters, an HTML element as the first parameter and library settings as the second parameter. You need to pass settings only if you want to modify default behaviors

lightGallery(document.getElementById('gallery-container'), {
    speed: 500,
    mode: 'fade',
    ...Other settings
});

lightGallery core

LightGallery comes with modular architecture. All the basic functionalities are available in the core module. You need to include plugins such if you need additional functionalities such as thumbnails, vide support, zoom, etc. Here you can find all lightGallery core settings. If you think something is missing, please check the respective plugins settings as well.

NameTypeDefault
addClass string""

Add custom class for gallery container This can be used to set different style for different galleries

allowMediaOverlap booleanfalse

If true, toolbar, captions and thumbnails will not overlap with media element This will not effect thumbnails if animateThumb is false Also, toggle thumbnails button is not displayed if allowMediaOverlap is false

Note - Changing the position of the media on every slide transition creates a flickering effect. Therefore, The height of the caption is calculated dynamically, only once based on the first slide caption.
if you have dynamic captions for each media, you can provide an appropriate height for the captions via allowMediaOverlap option

appendCounterTo string".lg-toolbar"

Where the counter should be appended

appendSubHtmlTo ".lg-sub-html"

control where the sub-html should be appended.

ariaDescribedby string""

aria-describedby attribute for gallery

ariaLabelledby string""

aria-labelledby attribute fot gallery

backdropDuration number300

Backdrop transition duration. Note - Do not change the value of backdrop via css.

closable booleantrue

If false user won't be abel to close the gallery at all This is useful for creating inline galleries.

closeOnTap booleantrue

allows clicks on black area to close gallery.

container HTMLElementdocument.body

Configure where the gallery should be appended. Useful to create inline galleries and more

controls booleantrue

If false, prev/next buttons will not be displayed.

counter booleantrue

Whether to show total number of images and index number of currently displayed image.

defaultCaptionHeight number0

Height of the caption for calculating allowMediaOverlap positions Note - this is only used to find the position of media item if allowMediaOverlap is true. Not for setting height of the captions Set 0 if you want to calculate the height of captions dynamically

download booleantrue

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.

dynamic booleanfalse

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

An array of objects (src, iframe, subHtml, thumb, poster, responsive, srcset sizes) representing gallery elements.

easing string"ease"

Slide animation CSS easing property

enableDrag booleantrue

Enables desktop mouse drag support

enableSwipe booleantrue

Enables swipe support for touch devices

escKey booleantrue

Whether the LightGallery could be closed by pressing the "Esc" key.

exThumbImage string""

Option to fetch different thumbnail image other than first image

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.


<div id="lightGallery">
    <a href="a.jpg" data-external-thumb-image="images/externalThumb.jpg" ><img src="thumb.jpg" /></a>
</div>

lightGallery(document.getElementById('lightGallery'), {
    exThumbImage: 'data-external-thumb-image'
})
extraProps []

Fetch custom properties from the selector

this is useful for plugin development By default lightGallery fetches and store all the props selectors to reduce frequent dom interaction for fetching props every time. If you need any addition data to be fetched and stored in the galleryItems variable, you can do this just by passing the prop names via extraProps


HTML:
<div id="lightGallery">
    <a href="a.jpg" data-custom-prop="abc"><img src="thumb.jpg" /></a>
    <a href="a.jpg" data-custom-prop="xyz"><img src="thumb.jpg" /></a>
</div>
JS:
lightGallery(document.getElementById('lightGallery'), {
    extraProps: ['customProp']
})
// Note - If you are using dynamic mode, you can pass any custom prop in the galleryItem
lightGallery(document.getElementById('lightGallery'), {
    dynamic: true,
    dynamicEl: [{
        src: 'img/img1.jpg',
        customProp:'abc',
    }]
})

getCaptionFromTitleOrAlt booleantrue

Option to get captions from alt or title tags.

height string"100%"

Height of the gallery. example '100%' , '300px'

hideBarsDelay number0

Delay for hiding gallery controls in ms. Pass 0 if you don't want to hide the controls

hideControlOnEnd booleanfalse

If true, prev/next button will be hidden on first/last image.

iframeHeight string"100%"

Set width for iframe.

iframeWidth string"100%"

Set width for iframe.

index number0

specify which slide should load initially

isMobile undefined

Function to detect mobile devices

keyPress booleantrue

Enable keyboard navigation

licenseKey string"0000-0000-000-0000"

If you are using lightGallery for commercial projects, you need to purchase a commercial license to get the license key. For projects that are compatible with GPLv3 license, please contact us for getting a license key at contact@lightgalleryjs.com. If you want to test lightGallery before purchasing a commercial license, you can use `0000-0000-000-0000` as a temporary license key

loop booleantrue

If false, will disable the ability to loop back to the beginning of the gallery from the last slide.

mobileSettings Partial{ controls: false, showCloseIcon: false, download: false, } as MobileSettings

Separate settings for mobile devices

Note - this is applied only at the time of loading by default controls and close buttons are disabled on mobile devices. use this options if you want to enable them or change any other settings for mobile devices Note - mobileSettings does not merge default values, You need to provide all mobileSettings including default values

mode "lg-slide"

Type of transition between images.

mousewheel booleanfalse

ability to navigate to next/prev slides on mousewheel

nextHtml string""

Custom html for next control

numberOfSlideItemsInDom number10

Control how many slide items should be kept in dom at a time

To improve performance by reducing number of gallery items in the dom, lightGallery keeps only the lowest possible number of slides in the dom at a time. This has a minimum value of 3

plugins []

preload number2

number of preload slides

will exicute only after the current slide is fully loaded. for example, if you click 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.

prevHtml string""

Custom html for prev control

selectWithin string""

By default selector element relative to the current gallery. Instead of that you can tell lightGallery to select element relative to another element. Example - '.my-selector-container' | '#my-selector-container' In the code this become selector = document.querySelector(this.s.selectWithin ).querySelectorAll(this.s.selector);

selector ""

Custom selector property instead of direct children.

Based on your markup structure, you can specify custom selectors to fetch media data for the gallery Pass "this" to select same element You can also pass HTMLCollection directly Example - '.my-selector' | '#my-selector' | this | document.querySelectorAll('.my-selector')

showAfterLoad booleantrue

Show Content once it is fully loaded

showBarsAfter number10000

Delay in hiding controls for the first time when gallery is opened

showCloseIcon booleantrue

If false, close button won't be displayed. Useful for creating inline galleries.

showMaximizeIcon booleanfalse

Show maximize icon. Useful for creating inline galleries.

slideDelay number0

Delay slide transitions.

This is useful if you want to do any action in the current slide before moving to next slide.

For example, fading out the captions before going to next slide. .lg-slide-progress class name is added to the current slide immediately after calling the slide method. But transition begins only after the delay

slideEndAnimation booleantrue

Enable slideEnd animation

speed number400

Transition duration (in ms).

startAnimationDuration number400

Zoom from image animation duration

startClass string"lg-start-zoom"

Start animation class for the gallery.

  • This can be used to change the zoom effect when the image is loaded
  • This is also applied when navigating to new slides
  • startClass will be empty zoomFromOrigin is true.

subHtmlSelectorRelative booleanfalse

Set to true if the selector in "data-sub-html" should use the current item as its origin.

supportLegacyBrowser booleantrue

Support legacy browsers

Currently this is used only for adding support to srcset attribute via picturefill library If true lightGallery will show warning message to include picturefill library

swipeThreshold number50

By setting the swipeThreshold (in px) you can set how far the user must swipe for the next/prev image.

swipeToClose booleantrue

allows vertical drag/swipe to close gallery false if option closable is false

videoMaxSize string"1280-720"

Video max size.

This can be over-written by passing specific size via data-lg-size attribute Recommended video resolution and & aspect ratios https://support.google.com/youtube/answer/6375112

width string"100%"

Width of the gallery. example '100%' , '300px'

zoomFromOrigin booleantrue

Enable zoom from origin effect.

You need to know the original image size upfront and provide it via data-lg-size attribute as data-lg-size="1920-1280" If you don't know, the size of a few images in the list, you can skip the data-lg-size attribute for the particular slides, lightGallery will show the default animation if data-lg-size is not available If you are using responsive images, you can pass a comma separated list of sizes combined with a max-width (up to what size the particular image should be used) example - data-lg-size="240-160-375, 400-267-480, 1600-1067" data-responsive="img-240.jpg 375, img-400.jpg 480" data-src="img-1600.jpg" In the above example, upto 375 width img.240.jpg and lg-size 240-160 will be used. Similarly, upto 480 pixel width size 400-267 and img-400.jpg will be used And above 480, lg-size 1600-1067 and img-1600.jpg will be used

  • At the moment, zoomFromOrigin options is supported only for image slides.
  • Will be false if dynamic option is enabled or galleryID found in the URL.
  • startClass will be empty if zoomFromOrigin is true to avoid css conflicts.

Zoom Plugin

LightGallery zoom plugins enable functionalities like pinch to zoom, double-tap, or double click to see the actual size, zoom in, zoom out, and more.

NameTypeDefault
actualSize booleantrue

Enable actual size icon.

actualSizeIcons ActualSizeIcons{ zoomIn: 'lg-zoom-in', zoomOut: 'lg-zoom-out', } as ActualSizeIcons

Actual size icons classnames. Specify classnames for both ZoomIn and ZoomOut states You can use `actualSizeIcons: { zoomIn: 'lg-actual-size', zoomOut: 'lg-zoom-out' }` to show actual size icons instead of zoom in and zoom out icons.

enableZoomAfter number300

Once the slide transition is completed, how much time should take zoom plugin to activate

Some css styles will be added to the images if zoom is enabled. So it might conflict if you add any 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.

scale number1

Value of zoom should be incremented/decremented

showZoomInOutIcons booleanfalse

Show zoom in, zoom out icons

zoom booleantrue

Enable/Disable zoom option

Thumbnails plugin

Thumbnails plugins is required to generate thumbnails for your gallery, it supports features like animated thumbnails, automatically load thumbnails from external videos, and more.

NameTypeDefault
alignThumbnails "middle"

Position of thumbnails.

animateThumb booleantrue

appendThumbnailsTo ".lg-components"

control where the thumbnails should be appended. By default, thumbnails are appended to '.lg-components' which has inbuilt open close transitions If you don't want initial thumbnails transitions, or want to do more customization, you can append thumbnails to the lightGalley outer div - Demo

currentPagerPosition "middle"

Position of selected thumbnail.

enableThumbDrag booleantrue

Enables desktop mouse drag support for thumbnails.

enableThumbSwipe booleantrue

Enables thumbnail touch/swipe support for touch devices

loadYouTubeThumbnail booleantrue

You can automatically load thumbnails for YouTube videos from YouTube by setting loadYouTubeThumbnail true

thumbHeight string"80px"

Height of each thumbnails. Applicable only if animateThumb is false.

thumbMargin number5

Spacing between each thumbnails

thumbWidth number100

Width of each thumbnails.

thumbnail booleantrue

Enable thumbnails for the gallery

thumbnailSwipeThreshold number10

By setting the thumbnailSwipeThreshold (in px) you can set how far the user must swipe for the next/prev slide.

toggleThumb booleanfalse

Enable toggle captions and thumbnails.

not applicable if allowMediaOverlap is false

youTubeThumbSize number1

You can specify the thumbnail size by setting respective number.

Video plugin

Video plugin is required to display videos in lightGallery. Video plugin supports, YouTube, Vimeo, Wistia,and HTML5 videos.

NameTypeDefault
autoplayFirstVideo booleantrue

Enable/DIsable first video autoplay.

Autoplay has to be managed using this setting. Autoplay in PlayerParams doesn't have any effect.

autoplayVideoOnSlide booleanfalse

Autoplay video on slide change

Make sure you set preload:"none"

gotoNextSlideOnVideoEnd booleantrue

Go to next slide when video is ended Note - this doesn't work with YouTube videos at the moment

videojs booleanfalse

Enbale videojs custom video player

on your document to enable videojs player

videojsOptions any

Videojs player options

vimeoPlayerParams anyfalse

Change Vimeo player parameters. You can find the list of vimeo player parameters from the following link Vimeo player parameters


lightGallery(document.getElementById('lightGallery'), {
    vimeoPlayerParams: {
        byline : 0,
        portrait : 0,
        color : 'CCCCCC'
    }
})
wistiaPlayerParams anyfalse

Change Wistia player parameters. You can find the list of Wistia player parameters from the following link Vimeo player parameters

youTubePlayerParams anyfalse

Change YouTube player parameters. You can find the list of YouTube player parameters from the following link YouTube player parameters


lightGallery(document.getElementById('lightGallery'), {
    youTubePlayerParams: {
        modestbranding : 1,
        showinfo : 0,
        controls : 0
    }
})

Hash plugin

lightGallery hash plugin lets you provide custom unique URLs for each gallery image. This link can be used to share media anywhere on the web. It allows you to navigate to different slides via browser back/forward buttons too.

NameTypeDefault
customSlideName booleanfalse

Custom slide name to use in the url when hash plugin is enabled

galleryId string"1"

Unique id for each gallery.

It is mandatory when you use hash plugin for multiple galleries on the same page.

hash booleantrue

Enable/Disable hash option

Autoplay plugin

lightGallery autoplay plugin supports automatic slideshow which can be stopped on the first user action. It supports progress bar that indicates the duration of the current slide.

NameTypeDefault
appendAutoplayControlsTo string".lg-toolbar"

Specify where the autoplay controls should be appended.

autoplay booleantrue

Enable autoplay plugin

autoplayControls booleantrue

Show/hide autoplay controls.

forceSlideShowAutoplay booleanfalse

If false autoplay will be stopped after first user action

progressBar booleantrue

Show autoplay progressBar

slideShowAutoplay booleanfalse

Enable slideshow autoplay

slideShowInterval number5000

The time (in ms) between each auto transition.

Rotate plugin

Rotate plugin support features like rotate clockwise, rotate anticlockwise, flip horizontal, flip vertical with single click.

NameTypeDefault
flipHorizontal booleantrue

Enable flip horizontal.

flipVertical booleantrue

Enable flip vertical.

rotate booleantrue

Enable/Disable rotate option

rotateLeft booleantrue

Enable rotate left.

rotateRight booleantrue

Enable rotate right.

Share plugin

lightGallery share plugin allows you to share your images/videos to social media platforms such as Twitter or Facebook with unique url. It supports adding your own social share button too.

NameTypeDefault
additionalShareOptions []

Array of additional share options

This can be used to build additional share options. Demo

facebook booleantrue

Enable Facebook share.

facebookDropdownText string"Facebook"

Facebook dropdown text.

pinterest booleantrue

Enable pinterest share.

pinterestDropdownText string"Pinterest"

Pinterest dropdown text

share booleantrue

Enable/Disable share options

twitter booleantrue

Enable twitter share.

twitterDropdownText string"Twitter"

Twitter dropdown text

Pager plugin

If you prefer minimal layouts, you can opt pagers plugin instead of thumbnails using the pager plugin. Pagers create minimal graphics that represent each slide, and hovering over each pager item, shows the correspondent thumbnails.

NameTypeDefault
pager booleantrue

Enable/Disable pager option

FullScreen plugin

lightGallery Fullscreen plugin supports native HTML5 fullscreen feature in the gallery. you can toggle fullscreen with one click

NameTypeDefault
fullScreen booleantrue

Enable/Disable fullscreen option

Comment box plugin

Comment plugin supports FaceBook and Disqus comments out of the box. Allows people to comment on slides using their Facebook or Disqus accounts. You can easily add your own comment widget as well.

NameTypeDefault
commentBox booleanfalse

Enable comment box

commentsMarkup string"<div id="lg-comment-box" class="lg-comment-box lg-fb-comment-box"><div class="lg-comment-header"><h3 class="lg-comment-title">Leave a comment.</h3><span class="lg-comment-close lg-icon"></span></div><div class="lg-comment-body"></div></div>"

Facebook comments default markup

disqusComments booleanfalse

Enable disqus comment box

disqusConfig false

Disqus comment config

fbComments boolean

Enable facebook comment box

Medium zoom plugin

MediumZoom plugin helps you create similar zooming experience as seen on medium. This is a very basic plugin created just to demonstrate the customizability of lightGallery v2.1.0

NameTypeDefault
backgroundColor string"#000"

Background color for the gallery This can be overwritten by passing background color via `lg-background-color` for each item

margin number40

Space between the gallery outer area and images

mediumZoom booleantrue

Enable/Disable medium like zoom experience

Edit this page on GitHub

← Get started
Events →