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: 'lg-fade', // other settings});
The same names apply in every package. In React and
Vue each core setting is a prop and each plugin’s settings
are one object prop named after the plugin, such as zoom={{ scale: 1.5 }}.
In Angular core settings are signal inputs and plugin
settings go to the plugin’s factory, such as withZoom({ scale: 1.5 }).
lightGallery core
lightGallery comes with modular architecture. All the basic functionalities are
available in the core module. You need to include plugins if you need
additional functionalities such as thumbnails, video 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.
If true, toolbar, captions and thumbnails will not overlap with media element
This will not affect 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 defaultCaptionHeight option
control where the sub-html should be appended.
If you choose '.lg-outer', you are responsible for placing the div at the right position.
'.lg-outer' is useful if you want to show custom HTML outside the normal gallery
Announce slide changes to assistive technology through a dedicated
polite live region (strings.slideAnnouncement + the slide caption).
While enabled, the counter and caption bar are not
separate live regions, the announcer is the single source of
slide-change announcements. Set to false to restore the previous
behavior (live counter and caption, no announcer).
See Accessibility.
Configure where the gallery should be appended.
Useful to create inline galleries and more
It is an empty string in the default settings and later assigned to document.body to avoid accessing document for SSR
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
Gallery reading direction: keyboard arrows, swipe advance and the
slide/thumbnail transforms follow it. Visual mirroring is the
opt-in lg-rtl.css layer - load it whenever this resolves to 'rtl'.
'auto' inherits the computed direction of the gallery element;
the default stays 'ltr' so upgrades never change behavior on
existing pages.
See Localization & RTL.
By default download url will be taken from data-src/href attribute but it is supported only in 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.
lightGallery can be instantiated and launched programmatically by setting this option to true and populating dynamicEl option (see below) with the definitions of images.
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.
this is useful for plugin development
By default lightGallery fetches and stores all the props selectors to
reduce frequent dom interaction for fetching props every time.
If you need any additional 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 galleryItemlightGallery(document.getElementById('lightGallery'), { dynamic: true, dynamicEl: [{ src: 'img/img1.jpg', customProp:'abc', }]})
Custom icons: SVG markup per icon name, rendered instead of the
built-in SVG icon set, bring your own icons without touching CSS.
Omitted names keep the built-in icon. State-pair
buttons (maximize/minimize, autoplayPlay/autoplayPause,
fullscreen/fullscreenExit) need both names provided; a
half-provided pair keeps the built-in pair. Size and color follow
the button (1em/currentColor-friendly SVGs recommended).
See Custom icons.
License key. lightGallery is free under the GPLv3; projects that keep
their source proprietary need a commercial license, and its key arrives
by email. Open-source projects can request a key at
contact@lightgalleryjs.com.
0000-0000-000-0000 is a temporary key for evaluation: it does not
limit any feature, it only logs a console warning. lightGallery 3 keys
start with LIG; a key from v1 or v2 logs a warning asking you to
upgrade. See License.
Note - this is applied only at the time of loading
by default controls and close buttons are disabled on mobile devices.
use this option 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
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
Pinching down on an un-zoomed image and releasing closes the
gallery (iOS Photos). Guarded: a pinch that went past fit zoom at
any point is a zoom correction and never closes. Requires
closable and the zoom plugin.
The plugins to enable for this gallery, as the constructors exported
by each plugin entry, for example [lgZoom, lgThumbnail]. A plugin's
settings do nothing until the plugin is listed here.
See Plugins.
will execute 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.
Reset to previous scrollPosition when lightGallery is closed
By default, lightGallery doesn't hide the scrollbar for a smooth opening transition.
If a user changes the scroll position, lightGallery resets it to the previous value
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')
By default the selector element is 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 becomes selector = document.querySelector(this.s.selectWithin).querySelectorAll(this.s.selector);
Show the toolbar buttons that repeat a touch gesture.
Zoom in, zoom out and actual size do what pinch and
double-tap already do. On by default, and turned off on touch
devices through mobileSettings.
See showGestureButtons.
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
This can be useful if you want to localize the lightGallery strings to other languages.
Use your own service to translate the strings and pass it via settings.strings
Every core and plugin label lives here; the per-plugin *PluginStrings objects are deprecated.
Strings merge per-key over the defaults, override only the keys
you need (the old provide-everything requirement is gone).
See Localization & RTL.
When the toolbar buttons do not fit beside the counter,
the lowest-priority ones move into a "More options" menu. Set to
false to let the buttons wrap onto a second row instead.
See toolbarOverflow.
Large-gallery virtualization. Off when undefined, the classic
behavior: every thumbnail renders and the mounted-slide window is
numberOfSlideItemsInDom.
slides overrides the mounted-slide pool size; thumbs
turns on thumbnail-strip windowing (only the visible thumbs plus an
overscan render, with spacers preserving the strip geometry), a
number is the overscan thumb count per side, 'auto' derives one
extra viewport per side. The window advances at commit points
(release, slide change, resize), never per pointer move.
See Virtualization.
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, up to 375 width img-240.jpg and lg-size 240-160 will be used.
Similarly, up to 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
When the gallery closes on a slide that has no thumbnail to return to
(the trigger is hidden or collapsed, as with the overflow items behind a
"+9 photos" tile, it has no data-lg-size, or the gallery is dynamic), the
slide shrinks to the centre of the stage and fades out instead of flying
to the thumbnail.
At the moment, the zoomFromOrigin option is supported only for image slides.
The opening flight is skipped 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.
Plugin dependency - You need to include Zoom plugin
in the document to use the following options.
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.
Once the slide transition is completed, how much time the zoom plugin should take 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.
Deprecated.Set these labels on the core strings object instead,
every user-facing string lives in that one contract. An explicitly set
key here still wins (alias).
Thumbnails plugin
The thumbnails plugin adds the thumbnail strip to your gallery. It supports
animated thumbnails, thumbnail scrubbing, and loads thumbnails for YouTube
videos automatically.
Plugin dependency - You need to include Thumbnails plugin
in the document to use the following options.
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 lightGallery outer div -
Demo
Scrub the gallery with the thumbnail strip: while the strip is
dragged (or gliding after a fling), the slide under the strip's
travel position becomes current immediately, without slide
transitions, the strip works like a scrubber instead of an
independent scroll area. The full strip travel spans the whole
gallery, so the first and last slides are always reachable.
Requires animateThumb; taps still navigate normally.
See Thumbnail scrubbing.
Deprecated.Set these labels on the core strings object instead,
every user-facing string lives in that one contract. An explicitly set
key here still wins (alias).
You can specify the thumbnail size by setting respective number.
Justified layout plugin
Justified layout plugin arranges the gallery’s trigger thumbnails in rows of
equal height and varying widths that fill the container edge to edge. See the
justified layout guide for usage across all
frameworks.
v3.0.0
Plugin dependency - You need to include Justified layout plugin
in the document to use the following options.
Enable the justified layout for the gallery's trigger thumbnails:
rows of equal height and varying widths that fill the container
edge to edge. Inline galleries only, dynamic mode has no trigger
grid to lay out. Each box shows as a placeholder and its thumbnail
fades in once loaded; put class="lg-justified" on the container
markup so nothing shows unorganized before the script runs.
See Justified layout.
Last-row policy: 'justify' scales the leftover row to fill the
width like every other row, 'start' keeps the row height aligned
to the reading start, 'hide' hides the leftover thumbnails.
How thumbnails appear as they load: 'row' reveals whole rows top
to bottom, each once every thumbnail in it has loaded; 'image'
reveals each thumbnail on its own as soon as it has loaded.
Until a thumbnail is revealed its box shows as a placeholder.
See Justified layout.
Row height (px) the layout aims for; actual rows land as close to
it as the aspect ratios allow.
Added in v3.0.0
Video plugin
Video plugin is required to display videos in lightGallery. Video plugin
supports YouTube, Vimeo, Wistia and HTML5 videos.
Player scripts - Vimeo and Wistia player control (automatic play and pause, moving to the next slide when a video ends) needs each provider’s player script. The plugin loads player.js and the Wistia player API on demand the first time a video plays, so there is nothing to include yourself.
Plugin dependency - You need to include Video plugin
in the document to use the following options.
Render provider video slides (YouTube/Vimeo/Wistia) as lite facades:
a poster with a play button, with the provider iframe created only
when the user presses play.
The facade poster falls back from the item poster to
the YouTube thumbnail endpoint (see loadYouTubePoster) to the item
thumb; a slide with no resolvable poster keeps the previous
eager-iframe behavior. Note autoplayFirstVideo/autoplayVideoOnSlide
force an immediate materialize by design. Set false for 2.x
eager-iframe behavior on all provider slides.
See Video facades.
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.
Plugin dependency - You need to include Hash plugin
in the document to use the following options.
'auto' uses the Navigation API where the browser
supports it and falls back to the History API everywhere else;
'history' and 'navigation' force an engine (an unsupported
'navigation' quietly falls back, the enhancement is never
load-bearing). The deep-link URL format is identical either way.
See Hash drivers.
Added in v3.0.0
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. After the last slide the slideshow continues from the
first; see stopping autoplay at the end.
Plugin dependency - You need to include Autoplay plugin
in the document to use the following options.
Deprecated.Set these labels on the core strings object instead,
every user-facing string lives in that one contract. An explicitly set
key here still wins (alias).
The time (in ms) between each auto transition.
The countdown starts once the slide on screen has loaded, so a slow
connection never advances past an image before it is visible.
Rotate plugin
The rotate plugin adds rotate clockwise, rotate anticlockwise, flip horizontal
and flip vertical, each with a single click.
Plugin dependency - You need to include Rotate plugin
in the document to use the following options.
Deprecated.Set these labels on the core strings object instead,
every user-facing string lives in that one contract. An explicitly set
key here still wins (alias).
lightGallery share plugin allows you to share your images/videos to social media
platforms such as X (Twitter) or Facebook with unique url. It supports adding your
own social share button too.
Plugin dependency - You need to include Share plugin
in the document to use the following options.
Prefer the OS share sheet (navigator.share) over the dropdown menu
when the browser supports it. The share button then opens the native
sheet with the slide's URL (per-item shareUrl, falling back to the
network share URLs, then the page URL); the dropdown remains as the
automatic fallback. URL-sharing only, the image file itself is never
attached.
Defaults to true on touch devices and false on desktop,
where the branded dropdown is kept for consistency.
See Web Share.
Deprecated.Set these labels on the core strings object instead,
every user-facing string lives in that one contract. An explicitly set
key here still wins (alias).
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.
Plugin dependency - You need to include Pager plugin
in the document to use the following options.
Deprecated.Set these labels on the core strings object instead,
every user-facing string lives in that one contract. An explicitly set
key here still wins (alias).
Comment box plugin
The comment plugin supports Facebook and Disqus comments out of the box, so
people can comment on slides with their Facebook or Disqus accounts. You can
add your own comment widget as well.
Plugin dependency - You need to include Comment box plugin
in the document to use the following options.
Deprecated.Set these labels on the core strings object instead,
every user-facing string lives in that one contract. An explicitly set
key here still wins (alias).
The medium zoom plugin opens an image in place with a minimal interface, the
zooming experience seen on Medium: no toolbar, no thumbnails, and a click
closes it again.
Plugin dependency - You need to include Medium zoom plugin
in the document to use the following options.
Origin crop plugin flies the zoom-from-origin animation from a cropped
thumbnail’s crop, so a cover-fitted grid tile grows into the full photo
instead of being squashed into its box.
v3.0.0
Plugin dependency - You need to include Origin crop plugin
in the document to use the following options.
Enable/Disable the origin crop plugin: zoom-from-origin flights from
cropped thumbnails (object-fit: cover,
background-size: cover) start from the part of the image
the thumbnail shows, at a uniform scale, and reveal the rest around it.
See Zoom from origin.
lightGallery