Responsive & Dynamic Image Lightbox Plugin - Chocolat

Chocolat is a jQuery Vanilla JavaScript image lightbox plugin used to create a responsive, full-sized lightbox gallery/slider on your webpage or within a specific container. Great for showcasing your grouped images in a pleasant way.

Install & Download:

# Yarn
$ yarn add chocolat

# NPM
$ npm install chocolat --save

Basic usage:

1. Include the Chocolat plugin's JS and CSS in your document.

<link rel="stylesheet" href="css/chocolat.css">
<script src="js/chocolat.js"></script>

2. Or import it as an ES module.

import Chocolat from 'chocolat';
@import '~chocolat/dist/css/chocolat.css';

3. Create a new lightbox from images within the document.

<a class="chocolat-image" href="1.jpg" title="Caption 1">
  <img src="thumb/1.jpg" />
</a>

<a class="chocolat-image" href="2.jpg" title="Caption 2">
  <img src="thumb/2.jpg" />
</a>

<!-- Responsive Image Delivery Is Supported As Well -->
<a class="chocolat-image" 
  href="320x180.png" 
  title="Caption 3"
  data-srcset="320x180.png 320w, 1280x720.png 1280w, 1920x1080.png 1920w"
  data-sizes="100vw">
  <img src="thumb/3.jpg" /> 
</a>

Chocolat(document.querySelectorAll('.chocolat-image'), {
  // options here
})

4. Or load images from an array as follows:

const images = [
      { 
        src: '1.jpg', 
        title: 'Caption 1' 
      },
      { 
        src: '2.jpg', 
        title: 'Caption 2' 
      },
      { 
        src: '320x180.png', 
        title: 'Caption 3', 
        sizes: '100vw', 
        srcset: '320x180.png 320w, 1280x720.png 1280w' 
      }
]

const myLightbox = Chocolat(images, {
      // options here
});

myLightbox.open();

5. All the customization options.

Chocolat(document.querySelectorAll('.chocolat-image'), {

  // target container
  // window or jquery object or jquery selector, or element
  container : document.body,

  // Add a custom css class to the parent of the lightbox
  className : '',

  // 'scale-down', 'contain', 'cover' or 'native'
  imageSize: 'scale-down', 

  // HTML5 feature. Hides the browser.
  fullScreen: false,

  // infinite loop
  loop: false,

  // Sets whether we can switch from one image to another
  linkImages : true,

  // Set index.
  setIndex  : 0,

  // index of the image that you want to start the series.
  firstImageIndex: 0,

  // last image index
  lastImageIndex: false,

  // current image index
  currentImageIndex: undefined,

  // allows to zoom in/out images
  allowZoom: true,

  // allows to close the lightbox on click outside
  closeOnBackgroundClick: true,

  // override the href-attribute for source
  imageSourceAttribute: 'href',

  // set title
  setTitle: function() {
    return ''
  },

  // set description
  description: function() {
    return this.images[this.settings.currentImageIndex].title
  },

  // set pagination
  pagination: function() {
    const last = this.settings.lastImageIndex + 1
    const position = this.settings.currentImageIndex + 1

    return position + '/' + last
  },

  // callbacks
  afterInitialize() {},
  afterMarkup() {},
  afterImageLoad() {},
  afterImageLoad() {},
  afterClose() {},

  // function returning the horizontal padding to add around the image when it's zoomed
  zoomedPaddingX: function(canvasWidth, imgWidth) {
    return 0
  },

  // Function returning the vertical padding to add around the image when it's zoomed
  zoomedPaddingY: function(canvasHeight, imgHeight) {
    return 0
  }
  
})

6. API methods.

// open
myLightbox.open();

// close
myLightbox.close();

// next image
myLightbox.next();

// previous image
myLightbox.prev();

// current image index
myLightbox.current();

// center the current image
myLightbox.position();

// return a HTMLElement composing the lightbox.
myLightbox.getElem('right');

// get option value
myLightbox.get('imageSize');

// update options
myLightbox.set('imageSize', 'contain');

Changelog:

v1.1.3 (2024-10-17)

• Added afterImageLoad
• Updated chocolat.css

v1.1.2 (2023-12-18)

• Add imageSource option to native JS

v1.1.0 (2022-07-12)

• Bugfix
• Drop support for IE, use v1.0.4 if you need IE support

v1.0.4 (2021-02-27)

• Fixed Fullscreen close does not work in safari

v1.0.3 (2020-07-18)

• Closing lightbox (from full-screen mode) using Esc throws TypeError

v1.0.2 (2020-06-12)

• Add 'afterClose' event

v1.0.1 (2020-04-30)

• Fix linkimages: false and keyboard navigation

v1.0.0 (2020-04-08)

• Rewritten in pure JavaScript

v0.4.21 (2018-11-12)

• Can be imported as a module

v0.4.15 (2016-12-23)

• added afterInitialize and afterImageLoad hooks

v0.4.14 (2016-06-15)

• hook instead of custom functions

v0.4.13 (2016-04-07)

• update

v0.4.12 (2016-03-16)

• update

v0.4.11 (2016-03-05)

• Fix fullscreen

2015-09-16

• v0.4.10

2015-07-13

• added new skin

2015-07-07

• updated demo, added data-chocolat-title attr

2015-07-05

• v0.4.5

---

This awesome jQuery plugin is developed by nicolas-t. For more Advanced Usages, please check the demo page or visit the official website.