> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.optis.me/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Swatch events & app integration

1. [OPTIS Color Swatch](/swatch)
2. [Developers](/swatch/developers)

# 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?.();
```

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

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