lightGallery V2

A lightbox is a small helper that shows a larger version of an image (or a video) on top of the current web page. While the larger image is visible, the rest of the page is dimmed so the user’s attention stays on the content. The technique was first made popular by Lightbox v2 and the name lightbox is now used as a generic term for any JavaScript library that offers this kind of overlay view.

lightGallery is a fast, modular and responsive JavaScript lightbox. It is well-suited for desktops, tablets and phones, supports keyboard navigation, mouse drag, touch gestures and even YouTube, Vimeo, Dailymotion, VK and HTML5 videos. Because lightGallery is modular, the core library only contains the basic gallery; every extra feature (thumbnails, zoom, full-screen, autoplay, share buttons, …) is provided by a plugin that you load only when you really need it.

lightGallery

Here’s a breakdown of the most important features:

Image and video galleries: Display image galleries, single videos or mixed galleries (images and videos in the same gallery). Supports YouTube, Vimeo, Dailymotion, VK and any HTML5 video format (MP4, WebM, Ogg, …).
Modular architecture: The core library is small and only handles slide navigation. All other features are loaded as plugins (lgThumbnail, lgZoom, lgFullscreen, lgAutoplay, lgShare, lgRotate, lgHash, lgPager, lgComment, lgVideo, …).
Touch-friendly: Built-in support for touch gestures on mobile devices (swipe, drag). Mouse drag works the same way on desktops.
Keyboard navigation: Arrow keys move between slides, Esc closes the gallery and F toggles full-screen (when the full-screen plugin is loaded).
Responsive: Automatically picks the right image size based on the viewport through the standard srcset / sizes attributes or the simpler data-responsive attribute.
Hardware-accelerated transitions: A large number of CSS3 transitions (slide, fade, zoom, scale, skew, rotate, …). All transitions are hardware-accelerated where the browser allows it.
Customisable: Every visible part of the gallery can be styled through CSS or Sass variables. Most plugins also expose options to change the default behaviour without touching any code.
Multiple instances: You can run as many independent galleries on the same page as you like.

The lightGallery website contains the original API documentation. The pages in this manual are not a copy of the original pages: they are restructured to match the style used in the rest of the J1 Template manuals and they describe the version of lightGallery (v2.8.3) that is shipped with the J1 Template.

The original documentation pages are based on lightGallery version v2.8.3 for the current J1 template version 2025.x. The idea of providing this documentation is not to simply copy the original pages as duplicates. For better readability and usability, all pages are restructured and enhanced by code examples or improved description texts.

The documentation pages for the J1 Template project will be used for the AI-based chat client (planned for 4th quarter of 2025). The agent will be trained by all available documentation pages of the template system to give users an easy-to-use source for using the J1 Template to create websites for their needs.

Usage

A lightGallery instance is created by calling the global lightGallery() function with two arguments:

The gallery container — a DOM element that wraps all the clickable thumbnails. This is the element on which lightGallery listens for click events.
An options object that selects which thumbnails open the gallery (selector) and configures every other behaviour (transition speed, plugins, captions, …).

Name Description

Name	Description
`element`	The gallery container element. Pass a real DOM element (for example obtained from `document.getElementById(…)`) – not a CSS selector string. lightGallery uses this element to listen for clicks and to dispatch its events.
`selector`	The clickable elements inside the gallery container. May be a CSS selector string (for example `'a'` or `'.gallery-item'`). Each match becomes a slide. If the option is omitted (the default), lightGallery treats every direct child of the container as a slide. Pass the special string `'this'` if the container element itself is the only slide.

element

The gallery container element. Pass a real DOM element (for example obtained from document.getElementById(…)) – not a CSS selector string. lightGallery uses this element to listen for clicks and to dispatch its events.

selector

The clickable elements inside the gallery container. May be a CSS selector string (for example 'a' or '.gallery-item'). Each match becomes a slide. If the option is omitted (the default), lightGallery treats every direct child of the container as a slide. Pass the special string 'this' if the container element itself is the only slide.

Initialization

A complete lightGallery setup needs the lightGallery JavaScript file (lightgallery.min.js) and the main stylesheet (lightgallery-bundle.min.css), plus one or more plugin scripts (lg-thumbnail.min.js, lg-zoom.min.js, …) for any extra features. Plugins are passed to lightGallery through the plugins option:

<!-- 1. Stylesheet (in <head>) -->
<link rel="stylesheet" href="css/lightgallery-bundle.min.css" />
<!-- 2. Core library (just before </body>) -->
<script src="js/lightgallery.min.js"></script>
<!-- 3. Plugins (just after the core library) -->
<script src="js/plugins/lg-thumbnail.min.js"></script>
<script src="js/plugins/lg-zoom.min.js"></script>
<!-- 4. Initialisation (just after the plugin scripts) -->
<script>
  const galleryEl = document.getElementById('my_gallery');
  const lg = lightGallery(galleryEl, {
    selector: 'a',
    speed:    500,
    plugins:  [lgThumbnail, lgZoom]
    // ... other options
  });
</script>

HTML pattern – unordered list

The unordered-list pattern fits well into Bootstrap-based layouts because the <li> elements can carry grid classes (col-xs-6 col-sm-4 col-md-3 …) so the thumbnail grid is responsive without any extra CSS:

<!-- gallery container (required) -->
<div id="my_gallery" class="gallery-block">
  <div class="title">My gallery title</div>
  <!-- list of slides (required) -->
  <ul class="row list-unstyled">
    <!-- single slide (required) -->
    <li class="col-xs-6 col-sm-4 col-md-3"
        data-src="path/to/large_1.jpg"
        data-sub-html="<h4>Caption: image 1</h4>">
      <a href="#">
        <img class="img-fluid" src="path/to/thumb_1.jpg" alt="Image 1" />
      </a>
    </li>
    <!-- more slides ... -->
    <li class="col-xs-6 col-sm-4 col-md-3"
        data-src="path/to/large_n.jpg"
        data-sub-html="<h4>Caption: image n</h4>">
      <a href="#">
        <img class="img-fluid" src="path/to/thumb_n.jpg" alt="Image n" />
      </a>
    </li>
  </ul>
</div>

HTML pattern – anchor tags

For galleries that do not need a Bootstrap-style responsive grid, the simpler anchor-tag pattern is easier to read. Each <a> element is a slide and its href attribute holds the URL of the large image (no data-src is needed in this case):

<div id="my_gallery" class="gallery-container">
  <a href="path/to/large_1.jpg"
     data-sub-html="<h4>Caption: image 1</h4>">
    <img src="path/to/thumb_1.jpg" alt="Image 1" />
  </a>
  <a href="path/to/large_2.jpg"
     data-sub-html="<h4>Caption: image 2</h4>">
    <img src="path/to/thumb_2.jpg" alt="Image 2" />
  </a>
  <!-- more slides ... -->
</div>
<script>
  const galleryEl = document.getElementById('my_gallery');
  lightGallery(galleryEl, { selector: 'a' });
</script>

Dynamic mode

Dynamic mode lets you open lightGallery without any thumbnail HTML on the page. Instead of reading the slides from the DOM, the gallery is built from a JavaScript array passed through the dynamicEl option. This is useful when the slides come from an API or are generated on the fly.

To use dynamic mode, set dynamic: true and provide the slide list through dynamicEl. After initialisation, call openGallery() on the returned instance to actually show the gallery (lightGallery will not open by itself in dynamic mode, because there are no thumbnails to click on):

const dynamicGallery = lightGallery(document.getElementById('open-btn'), {
  dynamic: true,
  dynamicEl: [
    {
      src:     'path/to/image_1.jpg',
      thumb:   'path/to/thumb_1.jpg',
      subHtml: '<h4>Image 1</h4><p>First image of the gallery.</p>'
    },
    {
      src:     'path/to/image_2.jpg',
      thumb:   'path/to/thumb_2.jpg',
      subHtml: '<h4>Image 2</h4><p>Second image of the gallery.</p>'
    }
    // ... more slides
  ],
  plugins: [lgThumbnail, lgZoom]
});
// open the gallery on the second slide (index = 1)
document.getElementById('open-btn').addEventListener('click', () => {
  dynamicGallery.openGallery(1);
});

Translating

lightGallery shows a number of short text fragments in its UI (button tool-tips and error messages). All of them are stored in the strings option of the core, plus one *PluginStrings option per plugin. You can translate any string by overriding the matching key:

const lg = lightGallery(galleryEl, {
  selector: 'a',
  speed:    500,
  plugins:  [lgThumbnail, lgZoom, lgFullscreen, lgAutoplay, lgRotate, lgShare],
  // Core strings (always present)
  strings: {
    closeGallery:       'Close gallery',
    toggleMaximize:     'Toggle maximize',
    previousSlide:      'Previous slide',
    nextSlide:          'Next slide',
    download:           'Download',
    playVideo:          'Play video',
    mediaLoadingFailed: 'Oops... Failed to load content...'
  },
  // Plugin-specific strings (only used if the matching plugin is loaded)
  thumbnailPluginStrings:  { toggleThumbnails:  'Toggle thumbnails' },
  zoomPluginStrings:       { zoomIn:            'Zoom in',
                             zoomOut:           'Zoom out',
                             viewActualSize:    'View actual size' },
  fullscreenPluginStrings: { toggleFullscreen:  'Toggle Fullscreen' },
  autoplayPluginStrings:   { toggleAutoplay:    'Toggle Autoplay' },
  rotatePluginStrings:     { flipVertical:      'Flip vertical',
                             flipHorizontal:    'Flip horizontal',
                             rotateLeft:        'Rotate left',
                             rotateRight:       'Rotate right' },
  sharePluginStrings:      { share:             'Share' }
});

Mobile settings

On small screens it is often useful to hide some of the controls (close button, download button, navigation arrows …) to keep the interface clean. lightGallery makes this easy through the mobileSettings option: any value placed there overrides the matching core setting when the gallery is opened on a touch device.

The default mobileSettings are:

mobileSettings: {
  controls:      false,    // hide previous / next arrows
  showCloseIcon: false,    // hide the close icon (swipe-to-close still works)
  download:      false     // hide the download button
}

You can override or extend the defaults like this:

const lg = lightGallery(galleryEl, {
  selector: 'a',
  // every value below is only used on mobile devices
  mobileSettings: {
    controls:        true,
    download:        false,
    rotate:          false,
    showCloseIcon:   true
  }
});

J1 Integration

J1 Theme ships with a full integration of lightGallery. For most galleries no manual configuration and no extra HTML is required: J1 generates the gallery markup and calls lightGallery() for you, based on a single YAML configuration file (j1_lightgallery_mgr.yml) that lists the gallery items and the plugin set you want to load.

The information in this section is only relevant if you want to extend the default integration – for example, to write your own plugin or to change the look of the gallery through Sass variables. For day-to-day usage, the YAML configuration is enough.

Plugin API

A plugin is a JavaScript class that adds extra features to the lightGallery core. The class only has to expose two methods: init(), which is called when the gallery is built, and destroy(), which is called when the gallery is taken down again.

The plugin receives the core lightGallery instance as the first argument of its constructor; from there it can read the user-supplied settings (this.core.settings), listen to gallery events (this.core.LGel.on(…)) and add buttons to the toolbar (this.core.$toolbar.append(…)).

The skeleton of a custom plugin looks like this:

class MyPlugin {
  // 1. The constructor receives the lightGallery core instance.
  constructor(instance) {
    this.core = instance;
    // 2. Read user options (and provide default values).
    this.settings = Object.assign(
      { myOption: true },          // defaults
      this.core.settings           // user-supplied options
    );
    return this;
  }
  // 3. init() is called once when the gallery is built.
  init() {
    if (!this.settings.myOption) {
      return;
    }
    // ... add UI, listen to events, etc.
  }
  // 4. destroy() is called when the gallery is destroyed.
  destroy() {
    // ... remove UI, detach listeners, etc.
  }
}
// 5. Pass the plugin to the core via the `plugins` option.
const lg = lightGallery(document.getElementById('my_gallery'), {
  selector: 'a',
  plugins:  [MyPlugin],
  myOption: true
});

Sass variables

The table below lists the most useful Sass variables. They are declared in the lightGallery source files and can be overridden in a custom Sass file before the lightGallery stylesheets are imported.

Name Default Description

Name	Default	Description
`$backdrop-opacity`	`1`	Opacity of the dark background that covers the page while the gallery is open. A value of `0` means transparent, `1` means fully opaque.
`$lg-toolbar-bg`	`rgba(0, 0, 0, 0.45)`	Background colour of the top toolbar.
`$lg-border-radius-base`	`2px`	Base border radius applied to gallery elements such as the toolbar buttons.
`$lg-theme-highlight`	`rgb(169, 7, 7)`	Colour used for highlighted parts of the gallery (active progress bar, active thumbnail border, …).
`$lg-icon-bg`	`rgba(0, 0, 0, 0.45)`	Background colour for icon buttons.
`$lg-icon-color`	`#999`	Default icon colour.
`$lg-icon-hover-color`	`#FFF`	Icon colour on mouse hover.
`$lg-counter-color`	`#e6e6e6`	Slide-counter font colour.
`$lg-counter-font-size`	`16px`	Slide-counter font size.
`$lg-next-prev-bg`	`$lg-icon-bg`	Background colour of the previous / next arrows.
`$lg-next-prev-color`	`$lg-icon-color`	Icon colour of the previous / next arrows.
`$lg-next-prev-hover-color`	`$lg-icon-hover-color`	Icon colour of the previous / next arrows on mouse hover.
`$lg-progress-bar-bg`	`#333`	Background colour of the autoplay progress bar.
`$lg-progress-bar-active-bg`	`$lg-theme-highlight`	Highlight colour of the autoplay progress bar.
`$lg-progress-bar-height`	`5px`	Height of the autoplay progress bar.
`$zoom-transition-duration`	`0.3s`	Length of the zoom-in / zoom-out animation.
`$lg-sub-html-bg`	`rgba(0, 0, 0, 0.45)`	Background colour of the caption (`sub-html`) area.
`$lg-sub-html-color`	`#EEE`	Caption (`sub-html`) text colour.
`$lg-thumb-toggle-bg`	`#0D0A0A`	Background colour of the toggle thumbnails button.
`$lg-thumb-toggle-color`	`$lg-icon-color`	Icon colour of the toggle thumbnails button.
`$lg-thumb-toggle-hover-color`	`$lg-icon-hover-color`	Icon colour of the toggle thumbnails button on mouse hover.
`$lg-thumb-bg`	`#0D0A0A`	Background colour of the thumbnail strip.
`$zindex-outer`	`1050`	Stacking order (`z-index`) of the gallery wrapper.
`$zindex-progressbar`	`1080`	Stacking order (`z-index`) of the autoplay progress bar.
`$zindex-controls`	`1080`	Stacking order (`z-index`) of the navigation controls.
`$zindex-toolbar`	`1080`	Stacking order (`z-index`) of the toolbar.
`$zindex-subhtml`	`1080`	Stacking order (`z-index`) of the caption area.
`$zindex-thumbnail`	`1080`	Stacking order (`z-index`) of the thumbnail strip.
`$zindex-pager`	`1080`	Stacking order (`z-index`) of the pager.
`$zindex-playbutton`	`1080`	Stacking order (`z-index`) of the video play button.
`$zindex-item`	`1060`	Stacking order (`z-index`) of a single slide.
`$zindex-backdrop`	`1040`	Stacking order (`z-index`) of the dark backdrop layer.

$backdrop-opacity

1

Opacity of the dark background that covers the page while the gallery is open. A value of 0 means transparent, 1 means fully opaque.

$lg-toolbar-bg

rgba(0, 0, 0, 0.45)

Background colour of the top toolbar.

$lg-border-radius-base

2px

Base border radius applied to gallery elements such as the toolbar buttons.

$lg-theme-highlight

rgb(169, 7, 7)

Colour used for highlighted parts of the gallery (active progress bar, active thumbnail border, …).

$lg-icon-bg

rgba(0, 0, 0, 0.45)

Background colour for icon buttons.

$lg-icon-color

#999

Default icon colour.

$lg-icon-hover-color

#FFF

Icon colour on mouse hover.

$lg-counter-color

#e6e6e6

Slide-counter font colour.

$lg-counter-font-size

16px

Slide-counter font size.

$lg-next-prev-bg

$lg-icon-bg

Background colour of the previous / next arrows.

$lg-next-prev-color

$lg-icon-color

Icon colour of the previous / next arrows.

$lg-next-prev-hover-color

$lg-icon-hover-color

Icon colour of the previous / next arrows on mouse hover.

$lg-progress-bar-bg

#333

Background colour of the autoplay progress bar.

$lg-progress-bar-active-bg

$lg-theme-highlight

Highlight colour of the autoplay progress bar.

$lg-progress-bar-height

5px

Height of the autoplay progress bar.

$zoom-transition-duration

0.3s

Length of the zoom-in / zoom-out animation.

$lg-sub-html-bg

rgba(0, 0, 0, 0.45)

Background colour of the caption (sub-html) area.

$lg-sub-html-color

#EEE

Caption (sub-html) text colour.

$lg-thumb-toggle-bg

#0D0A0A

Background colour of the toggle thumbnails button.

$lg-thumb-toggle-color

$lg-icon-color

Icon colour of the toggle thumbnails button.

$lg-thumb-toggle-hover-color

$lg-icon-hover-color

Icon colour of the toggle thumbnails button on mouse hover.

$lg-thumb-bg

#0D0A0A

Background colour of the thumbnail strip.

$zindex-outer

1050

Stacking order (z-index) of the gallery wrapper.

$zindex-progressbar

1080

Stacking order (z-index) of the autoplay progress bar.

$zindex-controls

1080

Stacking order (z-index) of the navigation controls.

$zindex-toolbar

1080

Stacking order (z-index) of the toolbar.

$zindex-subhtml

1080

Stacking order (z-index) of the caption area.

$zindex-thumbnail

1080

Stacking order (z-index) of the thumbnail strip.

$zindex-pager

1080

Stacking order (z-index) of the pager.

$zindex-playbutton

1080

Stacking order (z-index) of the video play button.

$zindex-item

1060

Stacking order (z-index) of a single slide.

$zindex-backdrop

1040

Stacking order (z-index) of the dark backdrop layer.

lightGallery API

lightGallery is a fast, modular and responsive JavaScript lightbox. The core library handles slide navigation, animations and the basic toolbar. Every extra feature (thumbnails, zoom, full-screen, autoplay, …) is provided by a plugin that can be loaded independently.

This chapter documents the API of lightGallery v2.8.3 (the version shipped with the J1 template). For each option you will find its type, its default value and a short description. The longer settings also come with a small example.

Initialization

The initialisation of lightGallery happens in four steps: load the CSS (1), load the JavaScript (2), place the gallery markup in the HTML body (3) and finally call the global lightGallery() function to wire everything together (4).

CSS load

Add the lightGallery bundle stylesheet inside the <head> of the document. The bundle file already contains every plugin stylesheet, so only one <link> tag is needed:

<head>
  <link rel="stylesheet" type="text/css"
        href="css/lightgallery-bundle.min.css" />
</head>

JS load

Include the lightGallery core script and the plugin scripts you want to use, just before the closing </body> tag. The order matters – plugins must be loaded after the core:

<body>
  ...
  <!-- 1. lightGallery core -->
  <script src="js/lightgallery.min.js"></script>
  <!-- 2. Plugins (load only the ones you need) -->
  <script src="js/plugins/lg-thumbnail.min.js"></script>
  <script src="js/plugins/lg-zoom.min.js"></script>
  <script src="js/plugins/lg-fullscreen.min.js"></script>
  <script src="js/plugins/lg-autoplay.min.js"></script>
  <script src="js/plugins/lg-share.min.js"></script>
  <script src="js/plugins/lg-rotate.min.js"></script>
  <script src="js/plugins/lg-hash.min.js"></script>
  <script src="js/plugins/lg-pager.min.js"></script>
  <script src="js/plugins/lg-video.min.js"></script>
  ...
</body>

HTML markup

lightGallery accepts almost any HTML structure. The only requirement is a gallery container that wraps every clickable slide.

Single image (the container is the slide itself)

<a id="my_gallery" href="img/img1.jpg">
  <img src="img/thumb1.jpg" alt="Image 1" />
</a>
<script>
  const el = document.getElementById('my_gallery');
  lightGallery(el, { selector: 'this' });
</script>

Container with <a> tags as slides

<div id="my_gallery">
  <a href="img/img1.jpg"><img src="img/thumb1.jpg" /></a>
  <a href="img/img2.jpg"><img src="img/thumb2.jpg" /></a>
</div>
<script>
  const el = document.getElementById('my_gallery');
  lightGallery(el, { selector: 'a' });
</script>

Container with <div> tags as slides

<div id="my_gallery">
  <div class="item" data-src="img/img1.jpg">
    <img src="img/thumb1.jpg" />
  </div>
  <div class="item" data-src="img/img2.jpg">
    <img src="img/thumb2.jpg" />
  </div>
</div>
<script>
  const el = document.getElementById('my_gallery');
  lightGallery(el, { selector: '.item' });
</script>

Container with <ul> / <li> (J1 default)

<ul id="my_gallery">
  <li data-src="img/img1.jpg">
    <img src="img/thumb1.jpg" />
  </li>
  <li data-src="img/img2.jpg">
    <img src="img/thumb2.jpg" />
  </li>
</ul>
<script>
  const el = document.getElementById('my_gallery');
  lightGallery(el, { selector: 'li' });
</script>

For J1 Template, a Bootstrap-based notation built on top of (unstyled) unordered lists is used. Each image is one <li> element with grid classes such as col-xs-6 col-sm-4 col-md-3 so the thumbnails are responsive (2 / 3 / 4 columns depending on the viewport size):

<!-- gallery container (id = "j1-lightgallery") -->
<div id="j1-lightgallery" class="j1-lg-galleryblock">
  <div class="title">My gallery title</div>
  <!-- slide list (id = "j1-lightgallery-ul") -->
  <ul id="j1-lightgallery-ul" class="row list-unstyled">
    <!-- one slide per <li> – 2/3/4 per row depending on viewport -->
    <li class="col-xs-6 col-sm-4 col-md-3"
        data-src="/assets/image/img_1.jpg"
        data-sub-html="<p>Caption text for img_1</p>">
      <a href="#">
        <img class="lg-thumbnail" src="/assets/image/thumb_1.jpg" />
      </a>
    </li>
    <!-- as many slides as needed ... -->
    <li class="col-xs-6 col-sm-4 col-md-3"
        data-src="/assets/image/img_n.jpg"
        data-sub-html="<p>Caption text for img_n</p>">
      <a href="#">
        <img class="lg-thumbnail" src="/assets/image/thumb_n.jpg" />
      </a>
    </li>
  </ul>
</div>

JS initialization

Once the markup is in place, call the global lightGallery() function with the gallery container element and an options object:

const galleryEl = document.getElementById('j1-lightgallery-ul');
const lg = lightGallery(galleryEl, {
  selector: 'li',
  mode:     'lg-fade',
  speed:    500,
  plugins:  [lgThumbnail, lgZoom],
  // ... more options
});

Core options

The table below lists the options of the lightGallery core. Each plugin adds further options of its own; those are documented in the Plugins section further down.

Name Type Default Description

mode

string

lg-slide

Type of transition between slides. lightGallery comes with many transitions; see chapter Transition styles for the full list.

easing

string

ease

CSS easing function used for the slide transition. Any valid transition-timing-function value is accepted (ease, ease-in, ease-out, cubic-bezier(…) …).

speed

number (ms)

400

Slide transition duration in milliseconds.

licenseKey

string

0000-0000-000-0000

lightGallery commercial license key. Leave the default value for non-commercial use; otherwise enter the key you received from the lightGallery author.

height

string

100%

Height of the gallery wrapper. Examples: 100%, 300px.

width

string

100%

Width of the gallery wrapper. Examples: 100%, 300px.

addClass

string

''

Custom CSS class added to the gallery wrapper. Useful when you want to apply different styles to different galleries on the same page.

startClass

string

lg-start-zoom

Animation class used while the gallery is opening.

backdropDuration

number (ms)

300

Length of the backdrop fade-in / fade-out animation.

Do not change the value of the backdrop opacity through CSS – use the $backdrop-opacity Sass variable or the backdropDuration option instead.

container

string | function | element

''

Element that the gallery is appended to. By default the gallery is attached to the body of the document. Pass a CSS selector, a DOM element or a function returning either of the two if you want to attach the gallery somewhere else.

startAnimationDuration

number (ms)

400

Length of the start animation that lifts the clicked thumbnail to the position of the full-size slide.

zoomFromOrigin

boolean

true

If true, the gallery opens with a zoom animation that starts from the clicked thumbnail. Set to false for a simple fade.

hideBarsDelay

number (ms)

0

Delay (in milliseconds) after which the gallery toolbars are hidden when the cursor is idle. A value of 0 keeps the bars visible at all times.

showBarsAfter

number (ms)

10000

How long the toolbars are kept visible right after the gallery has opened, regardless of hideBarsDelay.

slideDelay

number (ms)

0

Delay before a slide change starts. Useful for syncing the slide transition with another animation.

supportLegacyBrowser

boolean

true

Add fall-backs for older browsers (IE10/11, old mobile browsers). Disable for a slightly smaller runtime when you only target modern browsers.

allowMediaOverlap

boolean

false

If true, the thumbnail strip and the captions are allowed to overlap the main image. If false (the default), the main image is shrunk so that nothing overlaps it.

videoMaxSize

string

1280-720

Maximum dimensions used when displaying videos, in the form WIDTH-HEIGHT.

loadYouTubePoster

boolean

true

Automatically load the YouTube poster image as the placeholder for YouTube video slides.

defaultCaptionHeight

number (px)

0

Default caption height (in pixels) used while the gallery is calculating its layout. Set to a non-zero value when captions take a visible amount of vertical space, to avoid a small layout jump on opening.

ariaLabelledby

string

''

id of an element on the page that labels the gallery. Used to build the aria-labelledby attribute on the gallery wrapper for better accessibility.

ariaDescribedby

string

''

id of an element on the page that describes the gallery. Used for the aria-describedby attribute.

resetScrollPosition

boolean

true

If true, the page is scrolled back to its previous position when the gallery is closed.

hideScrollbar

boolean

false

If true, the page scrollbar is hidden while the gallery is open.

closable

boolean

true

If true, clicks on the dark backdrop close the gallery.

swipeToClose

boolean

true

If true, a vertical swipe gesture closes the gallery.

closeOnTap

boolean

true

If true, a tap on the slide closes the gallery (touch devices).

showCloseIcon

boolean

true

If true, the close icon is shown in the top-right corner of the toolbar.

showMaximizeIcon

boolean

false

If true, an extra maximize icon is shown next to the close icon.

loop

boolean

true

If false, the gallery does not loop back to the first slide after the last one (and vice versa).

escKey

boolean

true

If true, pressing Esc closes the gallery.

keyPress

boolean

true

If true, the left and right arrow keys move between slides.

trapFocus

boolean

true

If true, keyboard focus is trapped inside the gallery while it is open. Required for an accessible gallery.

controls

boolean

true

If false, the previous / next arrow buttons are hidden.

slideEndAnimation

boolean

true

If true, a small bounce animation plays when the user tries to go past the first or the last slide.

hideControlOnEnd

boolean

false

If true, the previous / next arrows are hidden on the first / last slide.

mousewheel

boolean

false

If true, the mouse wheel can be used to switch between slides.

getCaptionFromTitleOrAlt

boolean

true

If true and a slide has no data-sub-html attribute, the caption is read from the alt (or title) attribute of the thumbnail image.

appendSubHtmlTo

string

.lg-sub-html

CSS selector that points to the element where the caption (sub-html) is appended. Use .lg-sub-html for a caption outside the slide, or .lg-item for a caption inside the slide.

subHtmlSelectorRelative

boolean

false

If true, a data-sub-html value that starts with # or . is looked up inside the current slide instead of in the whole document.

preload

number

2

Number of slides to preload in the background. With the default of 2, the slides immediately before and after the current one are loaded ahead of time, so the user does not see a loading spinner when navigating.

numberOfSlideItemsInDom

number

10

Maximum number of slide elements that are kept in the DOM at the same time. Increasing this value uses more memory; decreasing it forces the gallery to re-create slide elements more often.

selector

string

''

CSS selector for the clickable slides. Pass 'this' if the gallery container is itself the only slide; pass 'a', '.item' or any other selector to match a list of children.

selectWithin

string | element

''

By default, lightGallery looks for slides inside the gallery container. Use this option to point to another element to look for slides in.

nextHtml

string

''

Custom HTML used as the next control button. Leave empty for the default arrow icon.

prevHtml

string

''

Custom HTML used as the previous control button.

index

number

0

Index of the slide that is shown first when the gallery opens.

iframeWidth

string

100%

Width of the iframe used for data-iframe="true" slides.

iframeHeight

string

100%

Height of the iframe used for data-iframe="true" slides.

iframeMaxWidth

string

100%

Maximum width of the iframe.

iframeMaxHeight

string

100%

Maximum height of the iframe.

download

boolean

true

If true, a download button is shown in the toolbar. The download URL is read from the data-download-url attribute (or, as a fall-back, from data-src / href). Pass false (or data-download-url="false" per slide) to hide the button.

counter

boolean

true

If true, a slide counter ("3 / 10") is shown in the toolbar.

appendCounterTo

string

.lg-toolbar

CSS selector of the element that the counter is appended to.

swipeThreshold

number (px)

50

Minimum distance (in pixels) the user has to swipe before the next or previous slide is shown.

enableSwipe

boolean

true

Enable touch-swipe support on touch devices.

enableDrag

boolean

true

Enable mouse-drag support on desktop browsers.

dynamic

boolean

false

If true, the gallery is built from the JavaScript array passed in dynamicEl instead of from the DOM. See the Dynamic mode section of the main page for an example.

dynamicEl

array

[]

Array of slide objects used in dynamic mode. Each object accepts the keys listed in the Dynamic variables table below (src, thumb, subHtml, …).

extraProps

array

[]

Names of extra data-* attributes whose values should be copied onto each slide object. Use this when you have your own custom data attributes that you want to read back inside event handlers.

isMobile

function

undefined

A user-supplied function that returns true when the gallery should switch to mobile mode. By default lightGallery uses a built-in detection routine.

mobileSettings

object

see below

Options that override the matching core settings on touch devices. The defaults are { controls: false, showCloseIcon: false, download: false }.

plugins

array

[]

Array of plugin classes to load. Order does not matter. Example: plugins: [lgThumbnail, lgZoom, lgFullscreen].

strings

object

see below

Translation strings used by the core toolbar buttons and error messages. The default object is { closeGallery: 'Close gallery', toggleMaximize: 'Toggle maximize', previousSlide: 'Previous slide', nextSlide: 'Next slide', download: 'Download', playVideo: 'Play video', mediaLoadingFailed: 'Oops… Failed to load content…' }.

Transition styles

lightGallery comes with a long list of CSS transitions for moving from one slide to the next. Use the mode option to pick the one you like:

Style Description

Style	Description
`lg-slide`	Default. Slides move horizontally, the new slide enters from the right (or from the left when going backwards).
`lg-fade`	The current slide fades out and the next slide fades in. No horizontal motion.
`lg-zoom-in`, `lg-zoom-in-big`	The new slide zooms in from a smaller scale. The `*-big` variant starts from an even smaller scale, so the zoom is more dramatic.
`lg-zoom-out`, `lg-zoom-out-big`	The current slide zooms out and disappears, then the next slide appears at full size. The `*-big` variant uses a stronger zoom-out.
`lg-zoom-out-in`, `lg-zoom-in-out`	Combines a zoom-out on the leaving slide with a zoom-in on the entering slide. `zoom-out-in` zooms out first then in; `zoom-in-out` does the reverse.
`lg-soft-zoom`	Subtle zoom transition – similar to `lg-zoom-in` but with a smaller scale change for a calmer effect.
`lg-scale-up`	The new slide scales up from `0` (invisible) to its full size.
`lg-slide-circular`, `lg-slide-circular-vertical`	Slide transition with a circular reveal. The vertical variant reveals the new slide from top to bottom instead of left to right.
`lg-slide-vertical`, `lg-slide-vertical-growth`	Slides move vertically (top to bottom). The `*-growth` variant combines the vertical move with a small grow-in effect.
`lg-slide-skew-only`, `lg-slide-skew-only-rev`	Plain skew transition – the slide tilts as it moves. The `*-rev` variant tilts in the opposite direction.
`lg-slide-skew-only-y`, `lg-slide-skew-only-y-rev`	Same as `lg-slide-skew-only` but the skew is applied on the vertical (Y) axis instead of the horizontal (X) axis.
`lg-slide-skew`, `lg-slide-skew-rev`	Combined slide + skew transition. The slide moves horizontally and tilts at the same time.
`lg-slide-skew-cross`, `lg-slide-skew-cross-rev`	Slide + skew transition where the leaving and entering slides skew in opposite directions, producing a cross-over effect.
`lg-slide-skew-ver`, `lg-slide-skew-ver-rev`	Vertical version of `lg-slide-skew`. Slides move vertically and tilt at the same time.
`lg-slide-skew-ver-cross`, `lg-slide-skew-ver-cross-rev`	Vertical version of `lg-slide-skew-cross`.
`lg-lollipop`, `lg-lollipop-rev`	Skew + scale + slide combination that gives a "swing" effect (like a swinging lollipop). The `*-rev` variant swings in the opposite direction.
`lg-rotate`, `lg-rotate-rev`	Slide transition combined with a rotation. The `*-rev` variant rotates in the opposite direction.
`lg-tube`	Slides appear to come out of a tube – horizontal slide combined with a small perspective tilt.

lg-slide

Default. Slides move horizontally, the new slide enters from the right (or from the left when going backwards).

lg-fade

The current slide fades out and the next slide fades in. No horizontal motion.

lg-zoom-in, lg-zoom-in-big

The new slide zooms in from a smaller scale. The *-big variant starts from an even smaller scale, so the zoom is more dramatic.

lg-zoom-out, lg-zoom-out-big

The current slide zooms out and disappears, then the next slide appears at full size. The *-big variant uses a stronger zoom-out.

lg-zoom-out-in, lg-zoom-in-out

Combines a zoom-out on the leaving slide with a zoom-in on the entering slide. zoom-out-in zooms out first then in; zoom-in-out does the reverse.

lg-soft-zoom

Subtle zoom transition – similar to lg-zoom-in but with a smaller scale change for a calmer effect.

lg-scale-up

The new slide scales up from 0 (invisible) to its full size.

lg-slide-circular, lg-slide-circular-vertical

Slide transition with a circular reveal. The vertical variant reveals the new slide from top to bottom instead of left to right.

lg-slide-vertical, lg-slide-vertical-growth

Slides move vertically (top to bottom). The *-growth variant combines the vertical move with a small grow-in effect.

lg-slide-skew-only, lg-slide-skew-only-rev

Plain skew transition – the slide tilts as it moves. The *-rev variant tilts in the opposite direction.

lg-slide-skew-only-y, lg-slide-skew-only-y-rev

Same as lg-slide-skew-only but the skew is applied on the vertical (Y) axis instead of the horizontal (X) axis.

lg-slide-skew, lg-slide-skew-rev

Combined slide + skew transition. The slide moves horizontally and tilts at the same time.

lg-slide-skew-cross, lg-slide-skew-cross-rev

Slide + skew transition where the leaving and entering slides skew in opposite directions, producing a cross-over effect.

lg-slide-skew-ver, lg-slide-skew-ver-rev

Vertical version of lg-slide-skew. Slides move vertically and tilt at the same time.

lg-slide-skew-ver-cross, lg-slide-skew-ver-cross-rev

Vertical version of lg-slide-skew-cross.

lg-lollipop, lg-lollipop-rev

Skew + scale + slide combination that gives a "swing" effect (like a swinging lollipop). The *-rev variant swings in the opposite direction.

lg-rotate, lg-rotate-rev

Slide transition combined with a rotation. The *-rev variant rotates in the opposite direction.

lg-tube

Slides appear to come out of a tube – horizontal slide combined with a small perspective tilt.

Data attributes

Each slide can be configured through data-* attributes on its container element. lightGallery reads these attributes when the gallery is built.

Name Description

Name	Description
`data-src`	URL of the large image or video. Required, unless `href` already points to the large image (anchor-tag pattern) or `data-html` is used to embed an HTML5 video.
`data-sub-html`	Caption HTML. May be either the literal HTML of the caption (e.g. `"<h4>Image 1</h4>"`) or the `id` / class of an element on the page that contains the caption HTML.
`data-sub-html-url`	URL of an external file whose contents are loaded as the caption. Useful for very long captions.
`data-html`	`id` (or class) of a hidden element on the page whose contents are used as the slide content. Mainly used to embed HTML5 video tags.
`data-poster`	URL of the poster image used as the placeholder for a video slide.
`data-responsive`	Comma-separated list of image URLs and breakpoints. Example: `img/1-375.jpg 375, img/1-480.jpg 480, img/1-757.jpg 757`. The browser picks the first image whose breakpoint is `⇐ viewport width`.
`data-srcset`	Standard `srcset` value (same syntax as the HTML `srcset` attribute).
`data-sizes`	Standard `sizes` value (same syntax as the HTML `sizes` attribute).
`data-iframe`	Set to `"true"` to open the URL in an `<iframe>` instead of an image / video viewer.
`data-download-url`	Custom download URL. Pass `"false"` to hide the download button for a single slide.
`data-width`	Natural width of the image in pixels. Used by the zoom plugin to display the actual size on a double-click.
`data-facebook-share-url`	URL used by the share plugin’s Facebook button. Defaults to the current page URL.
`data-twitter-share-url`	URL used by the share plugin’s Twitter button. Defaults to the current page URL.
`data-tweet-text`	Pre-filled tweet text used by the share plugin’s Twitter button.
`data-pinterest-share-url`	URL used by the share plugin’s Pinterest button. Defaults to the current page URL.
`data-pinterest-text`	Pre-filled description used by the share plugin’s Pinterest button.

data-src

URL of the large image or video. Required, unless href already points to the large image (anchor-tag pattern) or data-html is used to embed an HTML5 video.

data-sub-html

Caption HTML. May be either the literal HTML of the caption (e.g. "<h4>Image 1</h4>") or the id / class of an element on the page that contains the caption HTML.

data-sub-html-url

URL of an external file whose contents are loaded as the caption. Useful for very long captions.

data-html

id (or class) of a hidden element on the page whose contents are used as the slide content. Mainly used to embed HTML5 video tags.

data-poster

URL of the poster image used as the placeholder for a video slide.

data-responsive

Comma-separated list of image URLs and breakpoints. Example: img/1-375.jpg 375, img/1-480.jpg 480, img/1-757.jpg 757. The browser picks the first image whose breakpoint is ⇐ viewport width.

data-srcset

Standard srcset value (same syntax as the HTML srcset attribute).

data-sizes

Standard sizes value (same syntax as the HTML sizes attribute).

data-iframe

Set to "true" to open the URL in an <iframe> instead of an image / video viewer.

data-download-url

Custom download URL. Pass "false" to hide the download button for a single slide.

data-width

Natural width of the image in pixels. Used by the zoom plugin to display the actual size on a double-click.

data-facebook-share-url

URL used by the share plugin’s Facebook button. Defaults to the current page URL.

data-twitter-share-url

URL used by the share plugin’s Twitter button. Defaults to the current page URL.

data-tweet-text

Pre-filled tweet text used by the share plugin’s Twitter button.

data-pinterest-share-url

URL used by the share plugin’s Pinterest button. Defaults to the current page URL.

data-pinterest-text

Pre-filled description used by the share plugin’s Pinterest button.

Methods

The lightGallery() function returns the instance of the gallery. All methods are called directly on that instance.

const galleryEl = document.getElementById('my_gallery');
const lg = lightGallery(galleryEl, { selector: 'a' });
// Open the gallery on the third slide (index = 2)
lg.openGallery(2);

Name Parameters Description

Name	Parameters	Description
`openGallery(index, element)`	`index` (number, optional) `element` (DOM element, optional)	Open the gallery. `index` is the zero-based index of the slide to show first; `element` is the DOM element used as the origin of the zoom-from-thumbnail animation. Both arguments are optional.
`slide(index, fromTouch, fromThumb, direction)`	`index`, `fromTouch`, `fromThumb`, `direction`	Go to a specific slide. `index` is zero-based. The other three arguments are optional and only need to be set when you mimic a real user action; in normal code you can pass `false`, `false`, `false`.
`goToNextSlide(fromTouch)`	`fromTouch` (boolean, optional)	Move to the next slide.
`goToPrevSlide(fromTouch)`	`fromTouch` (boolean, optional)	Move to the previous slide.
`closeGallery(force)`	`force` (boolean, optional)	Close the gallery. Pass `true` to close even if a slide is currently busy with an animation.
`refresh(galleryItems)`	`galleryItems` (array, optional)	Refresh the gallery. Call this method after the underlying DOM has changed (slides added, removed or reordered). In dynamic mode you can also pass an array of new slide objects.
`updateSlides(items, index)`	`items` (array), `index` (number)	Replace the current slide list with a new one and jump to the slide at `index`. Used to programmatically swap the contents of the gallery.
`destroy()`	–	Close the gallery (if open) and tear down all event listeners. After this call the instance can no longer be used.

openGallery(index, element)

index (number, optional)
element (DOM element, optional)

Open the gallery. index is the zero-based index of the slide to show first; element is the DOM element used as the origin of the zoom-from-thumbnail animation. Both arguments are optional.

slide(index, fromTouch, fromThumb, direction)

index, fromTouch, fromThumb, direction

Go to a specific slide. index is zero-based. The other three arguments are optional and only need to be set when you mimic a real user action; in normal code you can pass false, false, false.

goToNextSlide(fromTouch)

fromTouch (boolean, optional)

Move to the next slide.

goToPrevSlide(fromTouch)

fromTouch (boolean, optional)

Move to the previous slide.

closeGallery(force)

force (boolean, optional)

Close the gallery. Pass true to close even if a slide is currently busy with an animation.

refresh(galleryItems)

galleryItems (array, optional)

Refresh the gallery. Call this method after the underlying DOM has changed (slides added, removed or reordered). In dynamic mode you can also pass an array of new slide objects.

updateSlides(items, index)

items (array), index (number)

Replace the current slide list with a new one and jump to the slide at index. Used to programmatically swap the contents of the gallery.

destroy()

–

Close the gallery (if open) and tear down all event listeners. After this call the instance can no longer be used.

Dynamic variables

The objects passed to dynamicEl accept the following keys (all are optional unless noted):

Name Description

Name	Description
`src`	URL of the large image or video. Required.
`thumb`	URL of the thumbnail image used by the thumbnail plugin and the zoom-from-thumbnail animation.
`subHtml`	Caption HTML, the `id` / class of an element on the page or a plain string. See `data-sub-html` for details.
`subHtmlUrl`	URL of an external caption file (loaded with `fetch`).
`alt`	`alt` text used as a fall-back caption when `getCaptionFromTitleOrAlt` is `true`.
`html`	`id` / class of a hidden element whose contents are used as the slide content. Mainly used for HTML5 video.
`video`	JSON object describing a video source. Used to render video slides without a separate `<video>` tag.
`poster`	URL of the poster image for video slides.
`responsive`	Comma-separated list of image URLs and breakpoints (same syntax as `data-responsive`).
`srcset`	Standard `srcset` value.
`sizes`	Standard `sizes` value.
`iframe`	Set to `true` to open `src` in an iframe.
`downloadUrl`	Custom download URL. Pass `false` to hide the download button.
`width`	Natural width of the image (used by the zoom plugin).
`slideName`	Custom slide name used by the hash plugin (when `customSlideName` is enabled).

src

URL of the large image or video. Required.

thumb

URL of the thumbnail image used by the thumbnail plugin and the zoom-from-thumbnail animation.

subHtml

Caption HTML, the id / class of an element on the page or a plain string. See data-sub-html for details.

subHtmlUrl

URL of an external caption file (loaded with fetch).

alt

alt text used as a fall-back caption when getCaptionFromTitleOrAlt is true.

html

id / class of a hidden element whose contents are used as the slide content. Mainly used for HTML5 video.

video

JSON object describing a video source. Used to render video slides without a separate <video> tag.

poster

URL of the poster image for video slides.

responsive

Comma-separated list of image URLs and breakpoints (same syntax as data-responsive).

srcset

Standard srcset value.

sizes

Standard sizes value.

iframe

Set to true to open src in an iframe.

downloadUrl

Custom download URL. Pass false to hide the download button.

width

Natural width of the image (used by the zoom plugin).

slideName

Custom slide name used by the hash plugin (when customSlideName is enabled).

Events

lightGallery dispatches a number of custom events on the gallery container element. Listen to them with the standard addEventListener() API:

const galleryEl = document.getElementById('my_gallery');
const lg = lightGallery(galleryEl, { selector: 'a' });
// Run before the gallery opens
galleryEl.addEventListener('lgBeforeOpen', (event) => {
  console.log('lgBeforeOpen');
});
// Run before each slide change.
// event.detail = { prevIndex, index, fromTouch, fromThumb }
galleryEl.addEventListener('lgBeforeSlide', (event) => {
  const { prevIndex, index, fromTouch, fromThumb } = event.detail;
  console.log('lgBeforeSlide', prevIndex, index, fromTouch, fromThumb);
});

Event Type event.detail Description

Event Type	`event.detail`	Description
`lgInit`	`instance`	Fired when the gallery instance is created (immediately after `lightGallery()` returns).
`lgBeforeOpen`	–	Fired right before the opening animation starts.
`lgAfterOpen`	–	Fired right after the opening animation has finished.
`lgAfterAppendSlide`	`index`	Fired when the slide content has been inserted into its slide container.
`lgAfterAppendSubHtml`	`index`	Fired when the caption (sub-html) has been appended to the slide.
`lgSlideItemLoad`	`index`, `delay`, `isFirstSlide`	Fired once the image (or video poster) inside the slide has finished loading.
`lgBeforeSlide`	`prevIndex`, `index`, `fromTouch`, `fromThumb`	Fired right before each slide transition. `fromTouch` is `true` when the change was triggered by touch / drag; `fromThumb` is `true` when the change was triggered by clicking a thumbnail.
`lgAfterSlide`	`prevIndex`, `index`, `fromTouch`, `fromThumb`	Fired right after each slide transition.
`lgBeforePrevSlide`	`index`, `fromTouch`	Fired right before a previous slide transition.
`lgBeforeNextSlide`	`index`, `fromTouch`	Fired right before a next slide transition.
`lgPosterClick`	–	Fired when the user clicks on the poster image of a video slide.
`lgDragStart`	–	Fired when the user starts dragging a slide.
`lgDragMove`	–	Fired periodically while a drag operation is in progress.
`lgDragEnd`	–	Fired when the user lets go after a drag.
`lgHasVideo`	`index`, `src`, `html5Video`, `videoStatus`	Fired when a slide that contains a video is being prepared.
`lgContainerResize`	–	Fired when the gallery container is resized (window resize, mobile orientation change, …).
`lgUpdateSlides`	–	Fired when `updateSlides()` has finished updating the slide list.
`lgRotateLeft`	`rotate`	Fired by the rotate plugin after a left rotation.
`lgRotateRight`	`rotate`	Fired by the rotate plugin after a right rotation.
`lgFlipHorizontal`	`flipHorizontal`	Fired by the rotate plugin after a horizontal flip.
`lgFlipVertical`	`flipVertical`	Fired by the rotate plugin after a vertical flip.
`lgAutoplay`	`index`	Fired by the autoplay plugin every time the autoplay timer moves to the next slide.
`lgAutoplayStart`	`index`	Fired by the autoplay plugin when autoplay starts.
`lgAutoplayStop`	`index`	Fired by the autoplay plugin when autoplay stops.
`lgBeforeClose`	–	Fired right before the closing animation starts.
`lgAfterClose`	–	Fired once the gallery has been fully closed.

lgInit

instance

Fired when the gallery instance is created (immediately after lightGallery() returns).

lgBeforeOpen

–

Fired right before the opening animation starts.

lgAfterOpen

–

Fired right after the opening animation has finished.

lgAfterAppendSlide

index

Fired when the slide content has been inserted into its slide container.

lgAfterAppendSubHtml

index

Fired when the caption (sub-html) has been appended to the slide.

lgSlideItemLoad

index, delay, isFirstSlide

Fired once the image (or video poster) inside the slide has finished loading.

lgBeforeSlide

prevIndex, index, fromTouch, fromThumb

Fired right before each slide transition. fromTouch is true when the change was triggered by touch / drag; fromThumb is true when the change was triggered by clicking a thumbnail.

lgAfterSlide

prevIndex, index, fromTouch, fromThumb

Fired right after each slide transition.

lgBeforePrevSlide

index, fromTouch

Fired right before a previous slide transition.

lgBeforeNextSlide

index, fromTouch

Fired right before a next slide transition.

lgPosterClick

–

Fired when the user clicks on the poster image of a video slide.

lgDragStart

–

Fired when the user starts dragging a slide.

lgDragMove

–

Fired periodically while a drag operation is in progress.

lgDragEnd

–

Fired when the user lets go after a drag.

lgHasVideo

index, src, html5Video, videoStatus

Fired when a slide that contains a video is being prepared.

lgContainerResize

–

Fired when the gallery container is resized (window resize, mobile orientation change, …).

lgUpdateSlides

–

Fired when updateSlides() has finished updating the slide list.

lgRotateLeft

rotate

Fired by the rotate plugin after a left rotation.

lgRotateRight

rotate

Fired by the rotate plugin after a right rotation.

lgFlipHorizontal

flipHorizontal

Fired by the rotate plugin after a horizontal flip.

lgFlipVertical

flipVertical

Fired by the rotate plugin after a vertical flip.

lgAutoplay

index

Fired by the autoplay plugin every time the autoplay timer moves to the next slide.

lgAutoplayStart

index

Fired by the autoplay plugin when autoplay starts.

lgAutoplayStop

index

Fired by the autoplay plugin when autoplay stops.

lgBeforeClose

–

Fired right before the closing animation starts.

lgAfterClose

–

Fired once the gallery has been fully closed.

Plugins

lightGallery plugins add extra features to the lightbox view, such as a thumbnail strip, a full-screen button, autoplay, social-share buttons or rotate controls. Plugins are loaded with the plugins option of the core – just import the plugin script in the HTML head and add the plugin class to the array:

<script src="js/plugins/lg-thumbnail.min.js"></script>
<script src="js/plugins/lg-zoom.min.js"></script>
<script>
  lightGallery(document.getElementById('my_gallery'), {
    selector: 'a',
    plugins:  [lgThumbnail, lgZoom]
  });
</script>

Thumbnails Plugin

You need to include the thumbnail plugin (lg-thumbnail.min.js) to use the options below. The plugin shows a strip of thumbnails at the bottom of the gallery and lets the user jump to any slide by clicking its thumbnail.

Name Type Default Description

Name	Type	Default	Description
`thumbnail`	boolean	`true`	Enable the thumbnail strip.
`animateThumb`	boolean	`true`	Animate the thumbnail strip when the active slide changes.
`currentPagerPosition`	string	`middle`	Where to position the active thumbnail inside the strip. Allowed values: `left`, `middle`, `right`.
`alignThumbnails`	string	`middle`	Vertical alignment of the thumbnail strip. Allowed values: `left`, `middle`, `right`.
`thumbWidth`	number (px)	`100`	Width of each thumbnail in pixels.
`thumbHeight`	string	`80px`	Height of each thumbnail (CSS length).
`thumbMargin`	number (px)	`5`	Spacing between two thumbnails in pixels.
`appendThumbnailsTo`	string	`.lg-components`	CSS selector of the element the thumbnail strip is appended to.
`toggleThumb`	boolean	`false`	If `true`, an extra toggle thumbnails button is shown so the user can hide / show the strip on demand.
`enableThumbDrag`	boolean	`true`	Enable mouse-drag support for the thumbnail strip (desktop).
`enableThumbSwipe`	boolean	`true`	Enable touch-swipe support for the thumbnail strip (mobile).
`thumbnailSwipeThreshold`	number (px)	`10`	Minimum swipe distance (in pixels) before the thumbnail strip starts to scroll.
`loadYouTubeThumbnail`	boolean	`true`	Automatically load the YouTube poster image as the thumbnail of YouTube video slides.
`youTubeThumbSize`	string \| number	`maxresdefault`	Size of the auto-generated YouTube thumbnail. See the YouTube ThumbSizes table below for the allowed values.
`thumbnailPluginStrings`	object	`{ toggleThumbnails: 'Toggle thumbnails' }`	Translation strings used by the thumbnail plugin.

thumbnail

boolean

true

Enable the thumbnail strip.

animateThumb

boolean

true

Animate the thumbnail strip when the active slide changes.

currentPagerPosition

string

middle

Where to position the active thumbnail inside the strip. Allowed values: left, middle, right.

alignThumbnails

string

middle

Vertical alignment of the thumbnail strip. Allowed values: left, middle, right.

thumbWidth

number (px)

100

Width of each thumbnail in pixels.

thumbHeight

string

80px

Height of each thumbnail (CSS length).

thumbMargin

number (px)

5

Spacing between two thumbnails in pixels.

appendThumbnailsTo

string

.lg-components

CSS selector of the element the thumbnail strip is appended to.

toggleThumb

boolean

false

If true, an extra toggle thumbnails button is shown so the user can hide / show the strip on demand.

enableThumbDrag

boolean

true

Enable mouse-drag support for the thumbnail strip (desktop).

enableThumbSwipe

boolean

true

Enable touch-swipe support for the thumbnail strip (mobile).

thumbnailSwipeThreshold

number (px)

10

Minimum swipe distance (in pixels) before the thumbnail strip starts to scroll.

loadYouTubeThumbnail

boolean

true

Automatically load the YouTube poster image as the thumbnail of YouTube video slides.

youTubeThumbSize

string | number

maxresdefault

Size of the auto-generated YouTube thumbnail. See the YouTube ThumbSizes table below for the allowed values.

thumbnailPluginStrings

object

{ toggleThumbnails: 'Toggle thumbnails' }

Translation strings used by the thumbnail plugin.

YouTube ThumbSizes

Value Size Description

Value	Size	Description
`0`	480x360 pixels	Player background thumbnail.
`1`	120x90 pixels	Default thumbnail size.
`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	Regular quality thumbnail.
`sddefault`	640x480 pixels	Standard definition thumbnail.
`maxresdefault`	1920x1080 pixels	Maximum resolution thumbnail. (default in J1 Template)

0

480x360 pixels

Player background thumbnail.

1

120x90 pixels

Default thumbnail size.

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

Regular quality thumbnail.

sddefault

640x480 pixels

Standard definition thumbnail.

maxresdefault

1920x1080 pixels

Maximum resolution thumbnail. (default in J1 Template)

sddefault and maxresdefault are optional on YouTube – they may or may not exist for a given video. If they do not exist, YouTube returns a placeholder image.

Autoplay Plugin

You need to include the autoplay plugin (lg-autoplay.min.js) to use the options below. The plugin starts a slideshow timer when the gallery opens (or only when the user clicks the play button).

Name Type Default Description

Name	Type	Default	Description
`autoplay`	boolean	`true`	Enable the autoplay plugin. Set to `false` to disable autoplay completely.
`slideShowAutoplay`	boolean	`false`	If `true`, the slideshow starts on its own once the gallery is open. If `false`, the user has to click the play button to start the slideshow.
`slideShowInterval`	number (ms)	`5000`	Time between two automatic slide changes, in milliseconds.
`progressBar`	boolean	`true`	Show a progress bar at the top of the gallery while autoplay is running.
`forceSlideShowAutoplay`	boolean	`false`	If `false` (the default), autoplay stops as soon as the user performs an action (click, swipe, …). Set to `true` to keep autoplay running regardless.
`autoplayControls`	boolean	`true`	Show the play / pause button in the toolbar.
`appendAutoplayControlsTo`	string	`.lg-toolbar`	CSS selector of the element the autoplay button is appended to.
`autoplayPluginStrings`	object	`{ toggleAutoplay: 'Toggle Autoplay' }`	Translation strings used by the autoplay plugin.

autoplay

boolean

true

Enable the autoplay plugin. Set to false to disable autoplay completely.

slideShowAutoplay

boolean

false

If true, the slideshow starts on its own once the gallery is open. If false, the user has to click the play button to start the slideshow.

slideShowInterval

number (ms)

5000

Time between two automatic slide changes, in milliseconds.

progressBar

boolean

true

Show a progress bar at the top of the gallery while autoplay is running.

forceSlideShowAutoplay

boolean

false

If false (the default), autoplay stops as soon as the user performs an action (click, swipe, …). Set to true to keep autoplay running regardless.

autoplayControls

boolean

true

Show the play / pause button in the toolbar.

appendAutoplayControlsTo

string

.lg-toolbar

CSS selector of the element the autoplay button is appended to.

autoplayPluginStrings

object

{ toggleAutoplay: 'Toggle Autoplay' }

Translation strings used by the autoplay plugin.

Video Plugin

You need to include the video plugin (lg-video.min.js) to use the options below. The plugin handles YouTube, Vimeo, Dailymotion, VK, and HTML5 video sources transparently.

Name Type Default Description

Name	Type	Default	Description
`autoplayFirstVideo`	boolean	`true`	If `true`, a video that is the first slide starts playing automatically.
`autoplayVideoOnSlide`	boolean	`false`	If `true`, every video starts playing automatically when its slide becomes active.
`gotoNextSlideOnVideoEnd`	boolean	`true`	If `true`, the gallery moves to the next slide when the current video has finished playing.
`youTubePlayerParams`	object \| boolean	`false`	Pass an object of YouTube player parameters here to customise the embedded YouTube player. See the YouTube Player Parameters documentation for the full list. Example `youTubePlayerParams: { showinfo: 0, controls: 0, modestbranding: 1 }`
`htmlPlayerParams`	object \| boolean	`false`	Pass an object of HTML5 `<video>` attributes (`muted`, `loop`, `playsinline`, …) to customise the native HTML5 player.
`videojs`	boolean	`false`	Use the video.js player to render HTML5 video slides. Requires loading the video.js library separately.
`videojsTheme`	string	`''`	Custom CSS class added to video.js players. Useful for applying a video.js theme.
`videojsOptions`	object	`{}`	Options passed to the video.js player when `videojs` is `true`.

autoplayFirstVideo

boolean

true

If true, a video that is the first slide starts playing automatically.

autoplayVideoOnSlide

boolean

false

If true, every video starts playing automatically when its slide becomes active.

gotoNextSlideOnVideoEnd

boolean

true

If true, the gallery moves to the next slide when the current video has finished playing.

youTubePlayerParams

object | boolean

false

Pass an object of YouTube player parameters here to customise the embedded YouTube player. See the YouTube Player Parameters documentation for the full list.

Example

youTubePlayerParams: {
  showinfo:    0,
  controls:    0,
  modestbranding: 1
}

htmlPlayerParams

object | boolean

false

Pass an object of HTML5 <video> attributes (muted, loop, playsinline, …) to customise the native HTML5 player.

videojs

boolean

false

Use the video.js player to render HTML5 video slides. Requires loading the video.js library separately.

videojsTheme

string

''

Custom CSS class added to video.js players. Useful for applying a video.js theme.

videojsOptions

object

{}

Options passed to the video.js player when videojs is true.

Fullscreen Plugin

You need to include the fullscreen plugin (lg-fullscreen.min.js) to use the options below. The plugin adds a fullscreen toggle button to the toolbar; clicking it switches the browser into real-fullscreen mode (using the standard requestFullscreen() API).

Name Type Default Description

Name	Type	Default	Description
`fullScreen`	boolean	`true`	Enable the fullscreen plugin.
`fullscreenPluginStrings`	object	`{ toggleFullscreen: 'Toggle Fullscreen' }`	Translation strings used by the fullscreen plugin.

fullScreen

boolean

true

Enable the fullscreen plugin.

fullscreenPluginStrings

object

{ toggleFullscreen: 'Toggle Fullscreen' }

Translation strings used by the fullscreen plugin.

You need to include the pager plugin (lg-pager.min.js) to use the options below. The plugin shows a small dot for every slide at the bottom of the gallery; the user can click any dot to jump directly to that slide.

Name Type Default Description

Name	Type	Default	Description
`pager`	boolean	`true`	Enable the pager plugin.

pager

boolean

true

Enable the pager plugin.

Zoom Plugin

You need to include the zoom plugin (lg-zoom.min.js) to use the options below. The plugin lets the user zoom into images using the mouse wheel, double-click, double-tap or pinch gestures.

Name Type Default Description

Name	Type	Default	Description
`zoom`	boolean	`true`	Enable the zoom plugin.
`scale`	number	`1`	How much each zoom step zooms in or out. A value of `1` means the zoom level changes by `1x` per step; a value of `2` doubles the zoom step.
`infiniteZoom`	boolean	`true`	If `true`, the user can keep zooming in past the actual image size. If `false`, zoom-in stops at the natural pixel size of the image.
`actualSize`	boolean	`true`	Enable the actual size icon (a button that resets the zoom to the natural pixel size of the image).
`showZoomInOutIcons`	boolean	`false`	If `true`, separate zoom-in and zoom-out icons are shown in the toolbar.
`actualSizeIcons`	object	`{ zoomIn: 'lg-zoom-in', zoomOut: 'lg-zoom-out' }`	CSS class names used for the zoom-in and zoom-out icons.
`enableZoomAfter`	number (ms)	`300`	Number of milliseconds to wait after a slide change before enabling the zoom. Increase this value if your custom CSS animations on the image conflict with the zoom transitions.
`zoomPluginStrings`	object	`{ zoomIn: 'Zoom in', zoomOut: 'Zoom out', viewActualSize: 'View actual size' }`	Translation strings used by the zoom plugin.

zoom

boolean

true

Enable the zoom plugin.

scale

number

1

How much each zoom step zooms in or out. A value of 1 means the zoom level changes by 1x per step; a value of 2 doubles the zoom step.

infiniteZoom

boolean

true

If true, the user can keep zooming in past the actual image size. If false, zoom-in stops at the natural pixel size of the image.

actualSize

boolean

true

Enable the actual size icon (a button that resets the zoom to the natural pixel size of the image).

showZoomInOutIcons

boolean

false

If true, separate zoom-in and zoom-out icons are shown in the toolbar.

actualSizeIcons

object

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

CSS class names used for the zoom-in and zoom-out icons.

enableZoomAfter

number (ms)

300

Number of milliseconds to wait after a slide change before enabling the zoom. Increase this value if your custom CSS animations on the image conflict with the zoom transitions.

zoomPluginStrings

object

{ zoomIn: 'Zoom in', zoomOut: 'Zoom out', viewActualSize: 'View actual size' }

Translation strings used by the zoom plugin.

Hash Plugin

You need to include the hash plugin (lg-hash.min.js) to use the options below. The plugin updates the URL hash (#lg=1&slide=3) every time the user moves to another slide, so the gallery state becomes bookmarkable. Visiting a URL that already contains a matching hash opens the gallery on that slide.

Name Type Default Description

Name	Type	Default	Description
`hash`	boolean	`true`	Enable the hash plugin.
`galleryId`	string \| number	`'1'`	Unique id used in the URL hash. Required when several galleries on the same page use the hash plugin (each gallery needs a different id).
`customSlideName`	boolean	`false`	If `true`, the slide name in the URL hash is taken from the `slideName` property of each slide instead of the slide’s index. The result is a friendlier URL such as `#lg=1&slide=image-of-mountains`.

hash

boolean

true

Enable the hash plugin.

galleryId

string | number

'1'

Unique id used in the URL hash. Required when several galleries on the same page use the hash plugin (each gallery needs a different id).

customSlideName

boolean

false

If true, the slide name in the URL hash is taken from the slideName property of each slide instead of the slide’s index. The result is a friendlier URL such as #lg=1&slide=image-of-mountains.

You need to include the share plugin (lg-share.min.js) to use the options below. The plugin adds a share dropdown button to the toolbar with one entry per supported social network. You can also add your own targets through the additionalShareOptions array.

Name Type Default Description

Name	Type	Default	Description
`share`	boolean	`true`	Enable the share plugin.
`facebook`	boolean	`true`	Show the Facebook share entry.
`facebookDropdownText`	string	`Facebook`	Label of the Facebook dropdown entry.
`twitter`	boolean	`true`	Show the Twitter share entry.
`twitterDropdownText`	string	`Twitter`	Label of the Twitter dropdown entry.
`pinterest`	boolean	`true`	Show the Pinterest share entry.
`pinterestDropdownText`	string	`Pinterest`	Label of the Pinterest dropdown entry.
`additionalShareOptions`	array	`[]`	Array of custom share targets. Each entry is an object with the keys `type`, `generateLink`, `dropdownHTML` and `selector` – see the source of `lg-share.js` for an example.
`sharePluginStrings`	object	`{ share: 'Share' }`	Translation strings used by the share plugin.

share

boolean

true

Enable the share plugin.

facebook

boolean

true

Show the Facebook share entry.

facebookDropdownText

string

Facebook

Label of the Facebook dropdown entry.

twitter

boolean

true

Show the Twitter share entry.

twitterDropdownText

string

Twitter

Label of the Twitter dropdown entry.

pinterest

boolean

true

Show the Pinterest share entry.

pinterestDropdownText

string

Pinterest

Label of the Pinterest dropdown entry.

additionalShareOptions

array

[]

Array of custom share targets. Each entry is an object with the keys type, generateLink, dropdownHTML and selector – see the source of lg-share.js for an example.

sharePluginStrings

object

{ share: 'Share' }

Translation strings used by the share plugin.

Rotate Plugin

You need to include the rotate plugin (lg-rotate.min.js) to use the options below. The plugin adds rotate-left, rotate-right, flip-horizontal and flip-vertical buttons to the toolbar.

Name Type Default Description

Name	Type	Default	Description
`rotate`	boolean	`true`	Enable the rotate plugin.
`rotateSpeed`	number (ms)	`400`	Length of the rotate / flip animation, in milliseconds.
`rotateLeft`	boolean	`true`	Show the rotate-left button.
`rotateRight`	boolean	`true`	Show the rotate-right button.
`flipHorizontal`	boolean	`true`	Show the flip-horizontal button.
`flipVertical`	boolean	`true`	Show the flip-vertical button.
`rotatePluginStrings`	object	`{ flipVertical: 'Flip vertical', flipHorizontal: 'Flip horizontal', rotateLeft: 'Rotate left', rotateRight: 'Rotate right' }`	Translation strings used by the rotate plugin.

rotate

boolean

true

Enable the rotate plugin.

rotateSpeed

number (ms)

400

Length of the rotate / flip animation, in milliseconds.

rotateLeft

boolean

true

Show the rotate-left button.

rotateRight

boolean

true

Show the rotate-right button.

flipHorizontal

boolean

true

Show the flip-horizontal button.

flipVertical

boolean

true

Show the flip-vertical button.

rotatePluginStrings

object

{ flipVertical: 'Flip vertical', flipHorizontal: 'Flip horizontal', rotateLeft: 'Rotate left', rotateRight: 'Rotate right' }

Translation strings used by the rotate plugin.

Comment Plugin

You need to include the comment plugin (lg-comment.min.js) to use the options below. The plugin adds a comments sidebar that embeds either Facebook comments or Disqus comments next to each slide.

Name Type Default Description

Name	Type	Default	Description
`commentBox`	boolean	`false`	Enable the comment plugin. Set to `true` and enable one of the two providers below.
`fbComments`	boolean	`false`	Enable Facebook comments. Each slide may carry an `fbHtml` property (in dynamic mode) or a `data-fb-html` attribute that contains the Facebook comments embed code.
`disqusComments`	boolean	`false`	Enable Disqus comments. Each slide may carry the `disqusIdentifier` and `disqusURL` properties (in dynamic mode) or the matching `data-*` attributes.
`disqusConfig`	object	`{ title: undefined, language: 'en' }`	Disqus configuration. Set `language` to your preferred Disqus language code; `title` is the page title used in the Disqus thread.
`commentsMarkup`	string	see source	HTML markup used for the comment sidebar. The default markup contains the empty `<div class="lg-comment-body"></div>` element into which the provider’s embed code is injected.
`commentPluginStrings`	object	`{ toggleComments: 'Toggle Comments' }`	Translation strings used by the comment plugin.

commentBox

boolean

false

Enable the comment plugin. Set to true and enable one of the two providers below.

fbComments

boolean

false

Enable Facebook comments. Each slide may carry an fbHtml property (in dynamic mode) or a data-fb-html attribute that contains the Facebook comments embed code.

disqusComments

boolean

false

Enable Disqus comments. Each slide may carry the disqusIdentifier and disqusURL properties (in dynamic mode) or the matching data-* attributes.

disqusConfig

object

{ title: undefined, language: 'en' }

Disqus configuration. Set language to your preferred Disqus language code; title is the page title used in the Disqus thread.

commentsMarkup

string

see source

HTML markup used for the comment sidebar. The default markup contains the empty <div class="lg-comment-body"></div> element into which the provider’s embed code is injected.

commentPluginStrings

object

{ toggleComments: 'Toggle Comments' }

Translation strings used by the comment plugin.

lightGallery

Usage

Initialization

HTML pattern – unordered list

HTML pattern – anchor tags

Dynamic mode

Translating

Mobile settings

J1 Integration

Plugin API

Sass variables

lightGallery API

Initialization

CSS load

JS load

HTML markup

JS initialization

Core options

Transition styles

Data attributes

Methods

Dynamic variables

Events

Plugins

Thumbnails Plugin

YouTube ThumbSizes

Autoplay Plugin

Video Plugin

Fullscreen Plugin

Pager Plugin

Zoom Plugin

Hash Plugin

Share Plugin

Rotate Plugin

Comment Plugin