> For the complete documentation index, see [llms.txt](https://chocolat.gitbook.io/chocolat/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://chocolat.gitbook.io/chocolat/usage.md).

# Usage

## Instanciating using HTML elements

You can directly bind Chocolat to `<a>` links, when clicked the lightbox will open.

```markup
<div>
    <a class="chocolat-image" href="img/a.jpg" title="image caption a">
        A <!-- you can display a thumbnail here : <img src="thumb/a.jpg" /> -->
    </a>
    <a class="chocolat-image" href="img/b.jpg" title="image caption b">
        B <!-- you can display a thumbnail here : <img src="thumb/b.jpg" /> -->
    </a>
</div>
```

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

You can also use `srcset` and `size`  attributes :

```markup
<div>
    <a class="chocolat-image" 
        href="demo-images/320x180.png" 
        title="image caption a"
        data-srcset="demo-images/320x180.png 320w,
            demo-images/1280x720.png 1280w,
            demo-images/1920x1080.png 1920w"
        data-sizes="100vw">
        A 
    </a>
</div>
```

## Instanciating using javascript objects

Sometimes you want more control over your images choosing how and when the lightbox will open.

```javascript
const images = [
    { src: 'img/a.jpg', title: 'image caption a' },
    { src: 'img/b.jpg', title: 'image caption b' },
    // ...
]

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

// open directly...
api.open()

// ...or when a specific element is clicked.
document.querySelector('#open-chocolat-link').addEventListener('click', () => {
    api.open()
})
```

You can also use `srcset` and `size`  attributes :

```javascript
const images = [
    { 
        src: 'img/a/320x180.png', 
        title: 'image caption a', 
        sizes: '100vw', 
        srcset: 'img/a/320x180.png 320w, img/a/1280x720.png 1280w' 
    },
    { 
        src: 'img/b/320x180.png', 
        title: 'image caption b', 
        sizes: '100vw', 
        srcset: 'img/b/320x180.png 320w, img/b/1280x720.png 1280w' 
    },
    // ...
]

// ...
```

You can find a more complete example in the `./demo/` folder: [here](https://github.com/nicolas-t/Chocolat/blob/ab712cae706c21eebd2515600db514752100e2e8/demo/index.html#L142-L235)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/usage.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.