Options

How to use options

Options is a javascript object passed as the second arguments of Chocolat.

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

For example : 

Chocolat(document.querySelectorAll('.chocolat-image'), {
    container: document.querySelector('#my-container'),
    loop: true,
    imageSize: 'cover',
    // ...
})

Options list

container

default : window type : HTMLElement

Sets whether lightbox will open and fill the whole page (default), or whether it should open in a particular block of the page. For example if we want to display the lightbox in the block #my-container:

{ 
    container: document.querySelector('#my-container')
}

imageSize

default : 'scale-down' type : String possible values : 'scale-down', 'contain', 'native', or 'cover'

For a more detailed explanations see the Images sizes page :

Image sizes

  • 'scale-down' : if the image is bigger than the window it's resized to fit.

    If the image is smaller than the window it's not streched, just displayed at native dimensions.

  • 'contain' : if the image is bigger than the window it's resized to fit. If the image is smaller than the window it's streched, to fit the window.

  • 'cover' : the image cover the window, no white spaces are displayed.

  • 'native' : the image is never streched nor shrinked, always displayed at native dimensions. 

{ 
    imageSize: 'cover'
}

linkImages

default : true type : Boolean

Sets whether we can switch from one image to another, without closing the viewer (true), or if the images can only be openned one by one (false). 

{ 
    linkImages: false
}

className

default : undefined type : String

Adds a custom css classes to the parent of the lightbox.

{ 
    className: 'my-first-custom-class my-second-custom-class'
}

loop

default : false type : Boolean

When true: last image + 1 leads to first image. first image - 1 leads to last image.

{ 
    loop: true
}

closeOnBackgroundClick

default : true type : Boolean

Closes Chocolat when the background is clicked.

{ 
    closeOnBackgroundClick: false
}

firstImageIndex

default : 0 type : Number

Index of the image that you want to start the series.

{ 
    firstImageIndex: 2
}

lastImageIndex

default : images.length - 1 type : Number

Index of the image that you want to start the series.

{ 
    lastImageIndex: 2
}

setTitle

default : undefined type : Function

Function returning the title of the image set. You can access the Chocolat instance inside the function unsing this.

{ 
    setTitle: function () { return 'Title of the set' }
}

description

default : title html attribute of the image type : Function

Function returning the description of the image. You can acces s the Chocolat instance inside the function unsing this.

{ 
    description: function () { 
        const currentImage = this.images[this.settings.currentImageIndex]
        return currentImage.title
    }
}

pagination

default : function returning position + '/' + last type : Function

Function returning the pagination informations. You can acces s the Chocolat instance inside the function unsing this.

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

imageSourceAttribute

default : 'href' type : String

Custom attribute to read the image source from.

{ 
    imageSourceAttribute: 'data-image-source'
}

fullScreen

default : false type : Boolean

Opens Chocolat fullscreen (hides the browser window).

{ 
    fullScreen: true
}

allowZoom

default : true type : Boolean

Disable or enable the zooming feature.

{ 
    allowZoom: false
}

afterInitialize

default : empty function type : Function

Function (hook) called just after chocolat gets initialized.

{ 
    afterInitialize: function () {
        // your logic here
    }
}

afterMarkup

default : empty function type : Function

Function (hook) called just after markup is created. You can use it to alter the default markup: to move the caption at the top of the image for example.

{ 
    afterMarkup: function () {
       this.elems.description.appendTo(this.elems.top)
    }
}

afterImageLoad

default : empty function type : Function

Function (hook) called just after an image is loaded.

{ 
    afterImageLoad: function () {
       // your logic here
    }
}

afterClose

default : empty function type : Function

Function (hook) called just after Chocolat is closed.

{ 
    afterClose: function () {
       // your logic here
    }
}

zoomedPaddingX

default : function returning 0 type : Function

Function returning the horizontal padding to add around the image when it's zoomed. It takes 2 arguments canvasWidth and imgWidth

{ 
   zoomedPaddingX: function (canvasWidth, imgWidth) {
       return canvasWidth / 2
   }
}

zoomedPaddingY

default : function returning 0 type : Function

Function returning the vertical padding to add around the image when it's zoomed. It takes 2 arguments canvasHeight and imgHeight

{ 
   zoomedPadding: function (canvasHeight, imgHeight) {
       return canvasHeight / 2
   }
}

PreviousUsageNextApi

Last updated