# Options

## How to use options  

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

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

For example : 

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

## Options list 

### container

*default :* `window`  \
\&#xNAN;*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`:

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

### imageSize

*default :* `'scale-down'`  \
\&#xNAN;*type : `String`* \
*possible values* : `'scale-down'`, `'contain'`, `'native'`, or `'cover'`

For a more detailed explanations see the **Images sizes** page :

{% content-ref url="/pages/-Lt9Oq8x6B-3TWU-MBrj" %}
[Image sizes](/chocolat/image-sizes.md)
{% endcontent-ref %}

* `'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.<br>

```javascript
{ 
    imageSize: 'cover'
}
```

### linkImages

*default :* `true`  \
\&#xNAN;*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`).&#x20;

```javascript
{ 
    linkImages: false
}
```

### className

*default :* `undefined`  \
\&#xNAN;*type : `String`*

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

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

### loop

*default :* `false`  \
\&#xNAN;*type : `Boolean`*

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

```javascript
{ 
    loop: true
}
```

### closeOnBackgroundClick

*default :* `true`  \
\&#xNAN;*type : `Boolean`*

Closes Chocolat when the background is clicked.

```javascript
{ 
    closeOnBackgroundClick: false
}
```

### firstImageIndex

*default :* `0`  \
\&#xNAN;*type : `Number`*

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

```javascript
{ 
    firstImageIndex: 2
}
```

### lastImageIndex

*default :* `images.length - 1`  \
\&#xNAN;*type : `Number`*

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

```javascript
{ 
    lastImageIndex: 2
}
```

### setTitle

*default :* `undefined`  \
\&#xNAN;*type :* `Function`

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

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

### description

*default :* `title` html attribute of the image \
\&#xNAN;*type :* `Function`

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

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

### pagination

*default :* function returning `position + '/' + last`  \
\&#xNAN;*type : `Function`*

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

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

### imageSourceAttribute

*default :* `'href'`  \
\&#xNAN;*type : `String`*

Custom attribute to read the image source from.

```javascript
{ 
    imageSourceAttribute: 'data-image-source'
}
```

### fullScreen

*default :* `false`  \
\&#xNAN;*type : `Boolean`*

Opens Chocolat fullscreen (hides the browser window).

```javascript
{ 
    fullScreen: true
}
```

### allowZoom

*default : `true`*\
\&#xNAN;*type : `Boolean`*

Disable or enable the zooming feature.

```javascript
{ 
    allowZoom: false
}
```

### afterInitialize

*default : `empty function`*\
\&#xNAN;*type : `Function`*

Function (hook) called just after chocolat gets initialized.

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

### afterMarkup

*default : `empty function`*\
\&#xNAN;*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.

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

### afterImageLoad

*default : `empty function`*\
\&#xNAN;*type : `Function`*

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

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

### afterClose

*default : `empty function`*\
\&#xNAN;*type : `Function`*

Function (hook) called just after Chocolat is closed.

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

### zoomedPaddingX

*default :* function returning `0`\
\&#xNAN;*type : `Function`*

Function returning the horizontal padding to add around the image when it's zoomed.\
&#x20;It takes 2 arguments `canvasWidth` and `imgWidth`

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

### zoomedPaddingY

*default :* function returning `0`\
\&#xNAN;*type : `Function`*

Function returning the vertical padding to add around the image when it's zoomed.\
&#x20;It takes 2 arguments `canvasHeight` and `imgHeight`

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://chocolat.gitbook.io/chocolat/options.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.