> For the complete documentation index, see [llms.txt](https://docs.optis.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optis.me/swatch/developers/swatch-events-and-integration.md).

# Swatch events & app integration

OPTIS Color Swatch exposes JavaScript events and a helper so developers can integrate the swatches with analytics, custom code, or other apps. This page is for developers, no setup is required for normal use.

## JavaScript events

The app dispatches the following **`CustomEvent`s on `document`** when the swatches render and when a shopper interacts with them on **collection pages**:

| Event name                               | Fires when                                                    | `event.detail`                                      |
| ---------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------- |
| `optis_swatch:variant-picker:rendered`   | The variant picker finishes rendering                         | `{ productInfo }`                                   |
| `optis_swatch:combined-listing:rendered` | A combined listing (Product Group) finishes rendering         | `{ productInfo }`                                   |
| `optis_swatch:variant:changed`           | The shopper selects a different variant                       | `{ selectedVariant, selectedOptions, productInfo }` |
| `optis_swatch:product:changed`           | The shopper selects a different product in a combined listing | `{ selectedProduct, selectedOptions, productInfo }` |

### Example: listen for variant changes

```javascript
document.addEventListener('optis_swatch:variant:changed', (event) => {
  const { selectedVariant, selectedOptions, productInfo } = event.detail;
  console.log('Variant changed:', selectedVariant, selectedOptions, productInfo);
  // e.g. send an analytics event here
});
```

## Re-render after another app updates the page

Some apps (collection filters, quick view, infinite scroll, page builders) replace part of the page with AJAX. When that happens, swatches in the newly injected content need to be re-rendered.

Call the helper to re-run OPTIS on the updated DOM:

```javascript
// Re-run OPTIS Color Swatch after another app injects new content
window.BSS_SE?.integrate?.runScript?.();
```

{% hint style="info" %}
Most popular filter and quick-view apps work automatically. Use `runScript()` only if you have a custom integration where swatches do not appear after content is replaced.
{% endhint %}

If you need help integrating with a specific app, contact our support team via live chat.


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.optis.me/swatch/developers/swatch-events-and-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.