Events

Sledge dispatches events as things happen on the storefront. Listening to them is the supported way to hook custom behavior in, and it is always preferable to watching the DOM yourself.

There are two namespaces, and the distinction matters.

Document-level events

These use a colon and fire on document. They are the ones you will use from custom code:

document.addEventListener('sledge:cart:updated', () => {
  // the cart changed — refresh your own UI
})

The most useful is sledge:product-card:rendered, which fires for every product card, on first render and again on every re-render:

document.addEventListener('sledge:product-card:rendered', (e) => {
  const card = e.detail?.card
  // A re-render rebuilt the shadow tree, so anything you injected is gone.
  // Re-apply here rather than assuming this runs once.
})

Others cover the cart, wishlist, reviews and toasts — the full list is in Reference → Events.

Element-level events

These use a hyphen and fire on the element that raised them. They bubble and cross shadow boundaries, so you can listen at the document level, but they tell you about one widget's interaction rather than a global state change:

document.addEventListener('sledge-filter-result', (e) => {
  // a filter query returned results
})

Use these when you care about a specific interaction — a filter changing, a search suggestion being selected, a sort order changing.

Choosing an approach

Full list

Reference → Events lists every event in both namespaces, with the feature that fires it.