GLightbox

3.3.1 · active · verified Sun Apr 19

GLightbox is a lightweight, pure JavaScript lightbox library designed for displaying various media types including images, videos (YouTube, Vimeo, self-hosted), iframes, and inline content. It is currently stable at version `3.3.1`, with an active beta release stream (`4.0.0-beta.x`) indicating ongoing development towards a new major version. The library is known for its small footprint (11KB gzipped), responsiveness across devices, and comprehensive feature set including gallery support, responsive images, keyboard and touch navigation, zoomable images, and a themeable API. It differentiates itself by being a feature-rich solution without external dependencies, offering a complete lightbox experience out-of-the-box, making it a robust choice for modern web projects requiring media presentation. While minor bug fixes and improvements are released frequently for the v3 branch, the v4 branch represents a significant refactor and enhancement effort.

Common errors

```
Uncaught ReferenceError: GLightbox is not defined
```
cause The GLightbox JavaScript file has not been loaded or is loaded incorrectly, or you are trying to use it before it's available.

fix Ensure `glightbox.min.js` is linked via a `<script>` tag in your HTML (preferably at the end of `<body>`), or properly imported via ESM/CommonJS if using a module bundler. If using a script tag, make sure your initialization script runs after `glightbox.min.js` has loaded.
```
Lightbox opens but content (image/video) is blank or shows a loading spinner indefinitely.
```
cause The linked media URL is incorrect, inaccessible (e.g., CORS issues for iframes/local files), or GLightbox cannot determine its content type.

fix Double-check the `href` attribute of your `<a>` tag. For external content, ensure it's publicly accessible. If linking to URLs without clear file extensions (e.g., a dynamic image URL or a generic API endpoint), explicitly set the `data-type` attribute (e.g., `data-type="image"` or `data-type="video"`) on the `<a>` tag.

Warnings

breaking GLightbox `v4.x` is currently in beta and introduces significant changes and refactors. Upgrading from `v3.x` will likely require modifications to your implementation due to API changes and a shift towards a plugin-based architecture.
Fix: Review the official GLightbox v4 migration guide (when available) before attempting to upgrade. For production, consider staying on the stable `v3.x` branch until `v4.0.0` is officially released.
gotcha The GLightbox CSS stylesheet must be explicitly included in your project. The JavaScript bundle does not automatically inject the styles, leading to an unstyled or non-functional lightbox if omitted.
Fix: Always link `glightbox.min.css` in your HTML `<head>` or import it into your main CSS/SCSS file if using a bundler (e.g., `import 'glightbox/dist/css/glightbox.min.css';`).
gotcha When initializing GLightbox, ensure the `selector` option accurately targets the elements you intend to trigger the lightbox. Mismatched selectors are a common cause of the lightbox not opening.
Fix: Verify that the `selector` string passed to `GLightbox()` matches the CSS class or attribute of your `<a>` tags. For example, if your links have `class="my-lightbox-item"`, initialize with `GLightbox({ selector: '.my-lightbox-item' });`

Install

npm install glightbox npm
yarn add glightbox yarn
pnpm add glightbox pnpm

Imports

GLightbox
wrong:
```
import { GLightbox } from 'glightbox';
```
correct:
```
import GLightbox from 'glightbox';
```
GLightbox is a default export when using bundlers like Webpack or Rollup. The library ships with TypeScript types.
GLightbox
wrong:
```
import GLightbox from 'glightbox'; // after script tag load
```
correct:
```
<script src="https://cdn.jsdelivr.net/npm/glightbox/dist/js/glightbox.min.js"></script>
<script>const lightbox = GLightbox();</script>
```
When loading GLightbox via a script tag (e.g., from a CDN), it exposes the `GLightbox` constructor globally on the `window` object. Do not attempt to use `import` syntax after a global script load.
CSS
wrong:
```
/* No CSS import */
```
correct:
```
import 'glightbox/dist/css/glightbox.min.css';
```
The GLightbox styles are not automatically included with the JavaScript. You must explicitly import the CSS file or link it in your HTML for the lightbox to be styled correctly.

Quickstart

This quickstart demonstrates how to set up a basic image and video gallery using GLightbox by including its CSS and JavaScript files from a CDN, and initializing it with a simple configuration. It showcases linking media with `<a>` tags and using `data-gallery` for grouping, and `data-glightbox` for inline titles/descriptions.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>GLightbox Quickstart</title>
    <!-- Essential: Link the GLightbox CSS -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/glightbox/dist/css/glightbox.min.css" />
</head>
<body>
    <h1>GLightbox Gallery Example</h1>

    <div class="gallery">
        <!-- Simple image with title and description -->
        <a href="https://picsum.photos/id/1015/1200/800" class="glightbox" data-gallery="mygallery" data-glightbox="title: Forest Path; description: A peaceful path through the woods.">
            <img src="https://picsum.photos/id/1015/300/200" alt="Forest Path" style="width:150px; height:auto;">
        </a>
        <!-- Another image in the same gallery -->
        <a href="https://picsum.photos/id/1018/1200/800" class="glightbox" data-gallery="mygallery" data-glightbox="title: Mountain Lake; description: Serene lake in the mountains.">
            <img src="https://picsum.photos/id/1018/300/200" alt="Mountain Lake" style="width:150px; height:auto;">
        </a>
        <!-- YouTube video example -->
        <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" class="glightbox" data-gallery="mygallery" data-glightbox="title: Rick Astley; description: Never Gonna Give You Up - official music video.">
            <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/mqdefault.jpg" alt="Rick Roll Thumbnail" style="width:150px; height:auto;">
        </a>
    </div>

    <!-- Essential: Link the GLightbox JavaScript -->
    <script src="https://cdn.jsdelivr.net/npm/glightbox/dist/js/glightbox.min.js"></script>
    <script type="text/javascript">
        // Initialize GLightbox. The selector targets all elements with the 'glightbox' class.
        const lightbox = GLightbox({
            selector: '.glightbox', 
            loop: true, // Allow looping through the gallery
            autoplayVideos: true // Automatically play videos when opened
        });

        // You can access the GLightbox instance for programmatic control if needed.
        // console.log('GLightbox initialized:', lightbox);
    </script>
</body>
</html>

view raw JSON →