lightGallery

lightGallery is a dependency-free JavaScript lightbox gallery plugin for building responsive image and video galleries. Its core handles gallery markup, slide transitions, and touch/drag gestures, while everything else — thumbnails, zoom, autoplay, fullscreen, rotation, social sharing, video playback (YouTube, Vimeo, Wistia, HTML5), and deep-linking via the browser history API — ships as opt-in plugins loaded only when needed, keeping the base bundle small.

The library is written in TypeScript and distributed as UMD, ES module, and CommonJS builds, with first-class wrapper packages for React, Vue, and Angular (plus a Lit build) published alongside the core so framework consumers get typed components instead of wrapping the vanilla API themselves. It supports over 20 hardware-accelerated CSS3 transitions, pinch-to-zoom and double-tap gestures for touch devices, keyboard navigation for desktop, and works with any HTML markup rather than imposing a required DOM structure.

What You Get

• Dependency-free core gallery engine with 20+ CSS3 transition effects
• Official framework wrappers published as separate packages for React, Vue, Angular, and Lit
• A plugin system (LgPlugin base class) covering thumbnails, zoom, autoplay, fullscreen, rotate, share, pager, hash deep-linking, and comments
• Built-in video support for YouTube, Vimeo, Wistia, and native HTML5 video via a dedicated video plugin
• Touch gesture handling — pinch to zoom, swipe/drag to navigate or close, double-tap for actual size
• Framework-agnostic markup — works with whatever HTML structure already wraps your images/videos

Common Use Cases

• Adding a lightbox to a static image gallery or portfolio site without a build step, via CDN script tags
• Building a product image gallery in a React, Vue, or Angular app using the official typed wrapper components
• Embedding a mixed image/video gallery that plays YouTube, Vimeo, or self-hosted HTML5 video inline
• Creating a dynamic, JS-driven gallery (no DOM markup required) fed from an API response
• Deep-linking directly to a specific gallery slide via URL hash for shareable links

Under The Hood

Architecture The core (src/lightgallery.ts, ~2,500 lines) is a single LightGallery class that owns gallery state (current index, open/closed, touch/swipe direction, busy flags) and DOM references ($container, $inner, $toolbar, etc.) built via a minimal internal jQuery-like wrapper (lgQuery.ts) rather than a full DOM library dependency. Plugins extend a two-line LgPlugin base class (src/lg-plugin.ts) that receives the core LightGallery instance and the lgQuery handle in its constructor, giving each plugin (autoplay, zoom, thumbnail, video, etc. under src/plugins/) direct access to core state and lifecycle events (src/lg-events.ts) without a formal dependency-injection layer — plugins are registered by passing their constructors into the plugins settings array at init time. Framework wrappers (lightgallery-react, lightgallery-vue, lightgallery-angular, lightgallery-lit at the repo root) are thin adapter packages that instantiate the vanilla core and translate framework component lifecycles into core init/destroy calls; the root tools/build-libraries and tools/update-packages scripts handle building and versioning them alongside the core so what breaks if the core settings shape changes is primarily these wrapper packages, not external consumers of the vanilla API.

Tech Stack Core is TypeScript compiled with tsc (ES5 target, ES2015 modules) and bundled via Rollup (rollup.config.ts) into UMD, ES5-module, and CommonJS outputs listed in package.json’s main/module/typings fields; styles are authored in SCSS (src/scss) and compiled with sass, then minified with clean-css-cli. The only runtime dependency is video.js (for the video plugin); React is a peer dependency for the React wrapper only. Docs are generated with TypeDoc into a site/ directory. There is no CI workflow file in the repository itself (.github/workflows is absent), and release automation is via semantic-release.

Code Quality Tests live under test/ and use Jest with ts-jest and @testing-library/dom/jest-dom for DOM assertions (lightgallery.test.ts, lg-video.test.ts); coverage thresholds in package.json’s Jest config are all set to 0, so tests exist but aren’t enforced as a coverage gate. Linting uses ESLint with a TypeScript plugin plus lint-staged/Husky pre-commit hooks, and TypeScript’s strict mode is enabled in tsconfig.json. Naming and file organization are consistent (lg-<feature>.ts per concern), and errors are generally handled through defensive checks and optional chaining rather than typed error objects.

What Makes It Unique Unlike most lightbox libraries that bundle every feature into one script, lightGallery’s plugin architecture lets consumers import only the effects they use (zoom, thumbnails, video, etc.) as separate modules, keeping the base bundle small while still supporting an extensive feature set. Shipping official, separately-versioned framework wrapper packages (React, Vue, Angular, Lit) alongside the vanilla core — rather than leaving framework integration to the community — is comparatively rare among comparable gallery plugins and is the project’s main differentiator.