JavaScript widget events

Color Swatches dispatches two custom events on document when its widgets finish rendering. Listen for them to attach analytics, re-bind theme code that depends on swatches, or update other parts of your page that need to stay in sync with swatch state.

pl-swatches-loaded

Fires once on the product page after the product widget renders its swatches.

document.addEventListener('pl-swatches-loaded', () => {
  console.log('Product swatches loaded');
});

The event fires once per product page render, which on a standard Shopify theme means once per page load.

pl-collection-swatches-loaded

Fires on the collection page every time the collection widget renders or re-renders.

document.addEventListener('pl-collection-swatches-loaded', () => {
  console.log('Collection swatches loaded');
});

The event can fire multiple times on the same page. Each time new product cards arrive (filter change, pagination, AJAX grid reload), the widget renders swatches for the new cards and dispatches the event again.

For DOM work on collection cards, listen for this event instead of DOMContentLoaded. Otherwise your code only runs against the first batch.

Common use cases

Analytics on swatch clicks. Attach a click handler to each swatch link as it appears:

document.addEventListener('pl-collection-swatches-loaded', () => {
  document.querySelectorAll('.pl-collection-swatches a').forEach((swatch) => {
    if (swatch.dataset.trackingAttached) return;
    swatch.dataset.trackingAttached = 'true';
    swatch.addEventListener('click', () => {
      window.dataLayer?.push({
        event: 'swatch_click',
        swatch_name: swatch.textContent.trim(),
      });
    });
  });
});

The dataset.trackingAttached guard avoids binding the same handler twice when the event fires again.

Keeping dependent UI in sync. If you have code that depends on swatch state (a “share this color” button, a custom price card), re-run it on each event so it matches what’s currently on the page.

Re-binding theme code. Some themes need a nudge after foreign elements appear in the DOM, like re-initialising a tooltip library or re-binding a quick-view trigger. The event is the right hook for that.