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

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:

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