API Docs

JavaScript image gallery, get started

View as Markdown Open in Claude Open in ChatGPT

lightGallery is a lightweight, modular, JavaScript library for creating beautiful image & video galleries for the web and the mobile.

Core features

Packages and build

One gallery, four packages: lightgallery for plain JavaScript and TypeScript, plus native React, Vue 3 and Angular packages that render their own DOM.
A shared headless core behind every package, so settings and behavior are identical in each stack.
Zero dependencies, TypeScript types, ES module and UMD builds. The core is about 19 KB minified and gzipped; plugins are separate entries and cost nothing until you import them.
Modular architecture with 15 built-in plugins, and an API for writing your own.
Easily customizable via CSS (SCSS) and settings. Multiple instances on one page.

Layout and performance

Fully responsive, with srcset, sizes and picture sources on every slide.
Justified layout plugin: row-justified trigger grids with no layout library in front of the lightbox.
Virtualization keeps a small, constant DOM for galleries with thousands of slides.
Dynamic mode opens a gallery from an array of items, and live updates add, edit or remove slides while it is open.
Inline gallery and carousel modes.
Smart preloading of neighboring slides.

Interaction

Highly optimized for touch devices, with mouse drag on desktops.
Gesture physics: every release lands in a spring seeded with your gesture’s velocity, flings glide, edges resist with friction.
Swipe, drag or pinch to close.
Zoom in and out, pinch to zoom, double-click or double-tap for actual size. Slides open from the thumbnail’s position and close back to it.
Animated thumbnails, with thumbnail scrubbing to drag through the gallery.
20+ hardware-accelerated CSS3 transitions, plus your own easing.
Keyboard navigation and full screen support.
A toolbar that fits: on narrow screens the lowest-priority buttons move into a “More options” menu.
Accessibility: modal dialog semantics, focus trap, screen-reader announcements, reduced-motion support.
Localization and RTL: every label is a setting, and the gallery mirrors for right-to-left pages.

Media and plugins

YouTube, Vimeo, Wistia and HTML5 video, with video facades that load the player only on play.
HTML iframe support and mixed content: photos, videos, maps and PDFs in one gallery.
HTML captions per slide, with animated and relative-position variants.
Rotate and flip images.
Sharing through the native share sheet where it exists, social links where it does not.
Deep links with browser back and forward, through the Navigation API or the History API.
Autoplay slideshow with a progress bar, pager dots, per-slide comments, and a medium-zoom plugin for in-page image zoom.
Inline SVG icons, each replaceable by name.

Ask your coding agent

Working with a coding agent? Paste the prompt below into it and replace the first line with the gallery you want. It points the agent at the markdown version of these docs, so it picks the right package for your stack and avoids the setup mistakes behind most bug reports.

Add lightGallery to this project: [describe the gallery you want, for
example "a product photo grid that opens a lightbox with thumbnails and
zoom"].

1. Detect the stack and use the matching package:
   - React: @lightgallery/react
   - Vue 3: @lightgallery/vue
   - Angular: @lightgallery/angular
   - Anything else (plain JavaScript, TypeScript, server-rendered HTML):
     lightgallery
2. Before writing code, read the docs index at
   https://www.lightgalleryjs.com/llms.txt and the guide for that stack:
   - React: https://www.lightgalleryjs.com/docs/react/index.md
   - Vue: https://www.lightgalleryjs.com/docs/vue/index.md
   - Angular: https://www.lightgalleryjs.com/docs/angular/index.md
   - Plain JavaScript:
     https://www.lightgalleryjs.com/docs/getting-started/index.md
   Use the install command from that guide exactly. The framework
   packages also need the lightgallery package, which ships the CSS.
3. Import the CSS yourself: lightgallery/css/lightgallery.css plus one
   file per plugin you use, such as lightgallery/css/lg-thumbnail.css.
   The framework packages ship no styles.
4. Plugins are opt-in. Import each one from its plugins/<name> entry and
   add it to the plugins list (in Angular, the features input with
   withThumbnail(), withZoom() and so on). A plugin's settings do
   nothing until the plugin is added. Unless I ask for something else,
   include the zoom and thumbnail plugins and their CSS files.
5. Give every item the full-size image URL, a thumbnail and alt text.
   Set lgSize to "WIDTH-HEIGHT" (data-lg-size in HTML markup) on every
   image item, using the natural size of the full image; read it from
   the image files, the image optimizer or the CMS. Without it the slide
   fades in instead of opening from its thumbnail.
6. Check every option name against
   https://www.lightgalleryjs.com/docs/settings/index.md instead of
   guessing. Commercial projects also need the licenseKey setting.
7. When you are done, run the project's build or type check, open the
   gallery in a browser, and confirm the styles are applied and the
   console shows no errors.

Installation

lightGallery is available on NPM, Yarn, CDNs, and GitHub. You can use any of the following methods to download lightGallery

NPM - NPM is a package manager for the JavaScript programming language. You can install lightgallery using the following command
```
npm install lightgallery
```
YARN - Yarn is another popular package manager for the JavaScript programming language. If you prefer you can use Yarn instead of NPM
```
yarn add lightgallery
```
GitHub - You can also download a release directly from GitHub
CDN - If you prefer to use a CDN, you can load files via jsdelivr, cdnjs or unpkg

Include CSS and Javascript files

First of all, include lightgallery.css in the <head> of the document. If you want to include any lightGallery plugin such as thumbnails or zoom, you need to include respective css files as well.

Alternatively you can include lightgallery-bundle.css which contains lightGallery and all plugin styles instead of separate stylesheets.

If you like you can also import scss files instead of css files from the scss folder.

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

    <!-- lightgallery plugins -->
    <link type="text/css" rel="stylesheet" href="css/lg-zoom.css" />
    <link type="text/css" rel="stylesheet" href="css/lg-thumbnail.css" />


    <!-- OR -->

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

Then include lightgallery.umd.js into your document. If you want to include any lightgallery plugin you can include it after lightgallery.umd.js.

<body>
    ....

    <script src="lightgallery.umd.js"></script>
    <!-- Or use the minified version -->
    <script src="lightgallery.min.js"></script>

    <!-- lightgallery plugins -->
    <script src="plugins/thumbnail/lg-thumbnail.umd.js"></script>
    <script src="plugins/zoom/lg-zoom.umd.js"></script>
</body>

lightGallery supports AMD, CommonJS and ES6 modules too.

import lightGallery from 'lightgallery';

// Plugins
import lgThumbnail from 'lightgallery/plugins/thumbnail'
import lgZoom from 'lightgallery/plugins/zoom'

The markup

lightGallery does not force you to use any kind of markup. You can use whatever markup you want. Here you can find detailed examples of different kinds of markups.

Give each anchor the natural size of its full image via data-lg-size="${width}-${height}". It drives the zoom-from-origin animation: the slide opens from the clicked thumbnail and closes back to it. Without the attribute the slide fades in instead.

<div id="lightgallery">
    <a href="img/img1.jpg" data-lg-size="1600-2400">
        <img alt="img1" src="img/thumb1.jpg" />
    </a>
    <a href="img/img2.jpg" data-lg-size="1024-800">
        <img alt="img2" src="img/thumb2.jpg" />
    </a>
    <!-- more items -->
</div>

Initialize lightGallery

Finally, you need to initiate the gallery by adding the following code.

<script type="text/javascript">
    lightGallery(document.getElementById('lightgallery'), {
        plugins: [lgZoom, lgThumbnail],
        licenseKey: 'your_license_key',
        speed: 500,
        // ... other settings
    });
</script>

License Key

You’ll receive a license key via email once you purchase a license More info

Plugins

As shown above, you need to pass the plugins via settings if you want to use any lightGallery plugins.

If you are including lightGallery files via script tag, please use the same plugins names as follows.

lgZoom, lgAutoplay, lgComment, lgFullscreen, lgHash, lgJustified, lgPager, lgRelativeCaption, lgRotate, lgShare, lgThumbnail, lgVideo, lgVimeoThumbnail, lgMediumZoom, lgOriginCrop

Browser support

lightGallery supports current evergreen browsers and iOS Safari: Chrome, Edge, Firefox and Safari on desktop, Safari on iOS and Chrome on Android. The builds target ES2017 and run without transpiling or polyfills.

ES module and UMD builds. Import it in a bundler, load it as a native <script type="module">, or drop the UMD file into a plain <script> tag. Nothing is module-only.
Newer APIs are optional. Features that rely on newer browser APIs, such as the native share sheet or observer-based relayout, are feature-detected and fall back cleanly where they are missing.

If something misbehaves in a browser you care about, please open an issue with the browser and version.

License

lightGallery is free and open source under the GPLv3. Use it in any project, personal or commercial, that is distributed under GPLv3-compatible terms.

If you want to keep your own source proprietary, choose the commercial license. It covers the same code with every feature and plugin included, nothing is gated, and it is a one-time payment. The license docs explain which license applies and how to pass your key.

Support

If the gallery misbehaves, the troubleshooting guide covers the symptoms behind most bug reports, with the fix for each package.

If you have any questions, suggestions, feedback, please reach out to contact@lightgalleryjs.com or DM me on X

Edit this page on GitHub