> 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.