Events & state

React to cart, variant, and wishlist changes; read shared client state.

Events

There is one event API. Platform code uses cartisto.events; every emit also dispatches a matching DOM CustomEvent on window, so a theme can subscribe either way. Names follow cartisto:<domain>:<verb>.

// SDK style
cartisto.events.on("cartisto:cart:updated", (detail) => updateBadge(detail.cart));
cartisto.events.off("cartisto:cart:updated", fn);

// or the standard browser API
window.addEventListener("cartisto:cart:updated", (e) => updateBadge(e.detail.cart));

Event	Fires when	Detail
`cartisto:cart:updated`	any cart mutation	`{ cart? }`
`cartisto:wishlist:ready`	wishlist ids primed on load	—
`cartisto:wishlist:changed`	a wishlist toggle succeeds	`{ productId, active }`
`cartisto:variant:change`	PDP variant selection changes	`{ variant, selected }`
`cartisto:listing:rendered`	the listing grid (re)painted	`{ count, total }`
`cartisto:listing:filtered`	filters/search applied	`{ filters }`

Events are the only extension surface. There are no cancelable before* hooks — intercepting a commerce path is a trust decision the platform doesn’t delegate to themes.

State

cartisto.state is one observable store for state shared between controllers on a page. It is not an SPA store — SSR still renders the page.

cartisto.state.get("wishlistIds");                 // Set<string>
cartisto.state.set("cart", cart);                  // notifies subscribers
const off = cartisto.state.subscribe("cart", render); // render(value) on each set
off();                                              // stop

Keys: cart, wishlistIds, customer, currency, locale. They’re seeded from server globals at load. Put shared client state here rather than inventing window.__* globals.

Seed globals

The platform emits page data in <head> as window.__NAME__ globals so mid-body theme scripts can read them:

Global	Page
`__TRANSLATIONS__`, `__CURRENT_LANGUAGE__`, `__IS_RTL__`, `__CURRENCY__`, `__BASE_CURRENCY__`, `__STORE_THEME__`	every page
`__INITIAL_CART__`	cart
`__PRODUCT__`, `__PRODUCT_BUNDLES__`	product
`__INITIAL_ACCOUNT__`	account
`__ORDER_DETAIL__`	order detail

Tip

Page action globals A few pages expose inline-handler actions on a namespaced global — window.cartistoListing.* (listing) and window.cartistoOrder.* (order detail). These are UI actions, kept off the API-only cartisto.* namespace.