GLightbox Documentation

GLightbox animations are driven by CSS classes. You define an effect (e.g., zoom) and map it to specific CSS animation names via the cssEfects option.

When an effect is triggered, GLightbox appends a g prefix to the animation name you provided. For example, if you register zoom: { in: 'zoomIn' }, GLightbox will apply the class .gzoomIn to the element.

const glightbox = GLightbox({
  openEffect: 'zoom',
  closeEffect: 'fade',
  cssEfects: {
    fade: { in: 'fadeIn', out: 'fadeOut' },
    zoom: { in: 'zoomIn', out: 'zoomOut' }
  }
});

// Adding a custom animation
const glightbox = GLightbox({
  openEffect: 'bounce',
  cssEfects: {
    bounce: { in: 'bounceIn', out: 'bounceOut' }
  }
});

Depending on your environment, you can import GLightbox using ESM specification or via a bundler like Webpack.

// Using ESM specification
import '/path/to/glightbox.js';

// Using a bundler like webpack
import GLightbox from 'glightbox';

You can install GLightbox as a dependency using your preferred package manager.

$ npm install glightbox
# OR
$ yarn add glightbox
# OR
$ bower install glightbox

For quick integration without a build step, you can link the CSS and JS files directly from a CDN in your HTML.

<!-- USING A CDN -->

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/glightbox/dist/css/glightbox.min.css" />
<script src="https://cdn.jsdelivr.net/gh/mcstudios/glightbox/dist/js/glightbox.min.js"></script>

<script type="text/javascript">
  const lightbox = GLightbox({ ...options });
</script>

To create a basic image lightbox, wrap an <img> tag in an <a> tag where the href points to the large image and the class is glightbox.

<!-- Simple image -->
<a href="large.jpg" class="glightbox">
  <img src="small.jpg" alt="image" />
</a>

You can add metadata to slides using the data-glightbox attribute with a semicolon-separated string, or by using individual data attributes.

<!-- Using data-glightbox attribute -->
<a href="large.jpg" data-glightbox="title: My title; description: this is the slide description">
  <img src="small.jpg" alt="image" />
</a>

<!-- Using individual data attributes -->
<a
  href="large.jpg"
  data-title="My title"
  data-description="description here"
  data-desc-position="right"
  data-type="image"
  data-effect="fade"
  data-width="900px"
  data-height="auto"
  data-zoomable="true"
  data-draggable="true"
></a>

To load content dynamically via AJAX, initialize GLightbox with an empty selector (selector: null or selector: ''). Once your data is fetched, use insertSlide or setElements to populate the lightbox before calling open() or openAt().

// Create an empty instance
const ajaxExample = GLightbox({ selector: null }); // or you can set the selector empty selector: ''

doAjaxCall({...}).then(response => {
    ajaxExample.insertSlide({
        width: '500px',
        content: response.html
    });
    ajaxExample.open();
})

// OR use setElements to replace everything
doAjaxCall({...}).then(response => {
    ajaxExample.setElements([
      {
        content: response.html
      }
    ]);
    ajaxExample.open();
})

When a slide contains a video, the player object is available in the event data. You can attach listeners to the player to handle playback states like ready, play, volumechange, and ended.

lightbox.on('slide_changed', ({ prev, current }) => {
  const { player } = current;

  if (player) {
    if (!player.ready) {
      player.on('ready', (event) => {
        // Do something when video is ready
      });
    }

    player.on('play', (event) => {
      console.log('Started play');
    });

    player.on('volumechange', (event) => {
      console.log('Volume change');
    });

    player.on('ended', (event) => {
      console.log('Video ended');
    });
  }
});

To group multiple items into a single gallery, add the data-gallery attribute with a unique name to each link.

<!-- Gallery -->
<a href="large.jpg" class="glightbox3" data-gallery="gallery1">
  <img src="small.jpg" alt="image" />
</a>
<a href="video.mp4" class="glightbox3" data-gallery="gallery1">
  <img src="small.jpg" alt="image" />
</a>

Wrap a thumbnail image in an <a> tag pointing to a video URL (YouTube, Vimeo, or local).

<!-- Video -->
<a href="https://vimeo.com/115041822" class="glightbox2">
  <img src="small.jpg" alt="image" />
</a>