JavaScript API & events

The storefront scripts expose a set of window globals and dispatch DOM events. Use them to react to wishlist changes, to re-scan the page after your theme updates it with AJAX, and to debug placement.

Only the globals and events listed here are meant for theme developers. Other window.cb* names are internal and can change between releases.

Events

`cb:wishlists-changed`

Dispatched on document whenever a wishlist is created, renamed or deleted, or when an item is added or removed.

document.addEventListener('cb:wishlists-changed', function (event) {
  // event.detail.source: 'icon' | 'icon-popup' | 'page' | 'nav' | ...
  console.log('Wishlist changed from', event.detail.source, event.detail);
  updateMyHeaderCounter();
});

`detail.source`	Sent by	Extra fields
`icon`	A heart or button toggled directly (single-list mode)	`variantId`
`icon-popup`	The “Add to wishlist” popup	—
`page`	The wishlist page	depends on the action
`nav`	The nav shortcode’s “Create new list”	`action: 'create'`, `wishlistId`, `name`

`cb:variant-changed`

Dispatched when the app sees a variant change on a product page or inside a product card.

document.addEventListener('cb:variant-changed', function (event) {
  const { variantId, productId, handle, container } = event.detail;
  // container === null means a page-level change (main product form)
});

The app learns about variant changes from the theme’s variant:changed event and from the URL’s ?variant= parameter. If your theme changes variants without either, dispatch variant:changed yourself:

document.dispatchEvent(new CustomEvent('variant:changed', {
  detail: { variant: { id: 44012345678901 } }
}));

`cb:wishlist-view-changed`

Dispatched by the wishlist page when it switches between a list and a wishlist’s detail view. detail.wishlistId holds the open wishlist ID.

Cart events

After a shopper adds a product to the cart from the wishlist page, the app dispatches these events on both document and window, with detail: { cart, source: 'cb-wishlist' }: cart:refresh, cart:updated, cart:build, cart:change, cart:open, cart-drawer:open, drawer:open On Dawn-based themes it also publishes PUB_SUB_EVENTS.cartUpdate. Listen to whichever event your theme’s cart drawer understands.

Re-scanning after AJAX updates

The app watches the DOM and rescans on shopify:facet:changed, shopify:section:load and popstate. If your theme loads products in a way the app misses (custom infinite scroll, a quick-view built from scratch), trigger a rescan yourself:

// Add hearts to newly loaded product cards
window.forceWishlistInjection && window.forceWishlistInjection();

// Re-sync the filled/empty state of every heart and button
window.updateAllIconsState && window.updateAllIconsState();

// Refresh the nav shortcode
window.cbWishlistNavRefresh && window.cbWishlistNavRefresh();

Useful globals

Identity and settings

Global	Type	Description
`window.customerId`	string	Logged-in customer ID, empty for guests
`window.wishlistUser`	object	`{ customerId, email, firstName, lastName, fullName }`
`window.getSessionId()`	function	Returns the guest session ID (`sid_…`)
`window.shop`	string	`*.myshopify.com` domain
`window.widgetSettings`	object	Resolved widget settings for the current language
`window.widgetSettingsPromise`	Promise	Resolves to the widget settings
`window.featuresPromise`	Promise	Resolves to the feature toggles
`window.productIdinWishlist`	Set	Variant IDs that are in any of the shopper’s wishlists

Wishlist mode and guests

Function	Returns
`window.cbIsSingleMode()`	`true` in single-wishlist mode
`window.cbResolveWishlistMode()`	Promise of `'single'` or `'multiple'`
`window.cbCanSaveWishlist()`	`false` when guests are blocked and the shopper is not logged in
`window.cbPromptLogin()`	Shows the “Please log in” toast with a login link
`window.cbLoginUrl()`	Login URL that returns the shopper to the current page

UI helpers

Function	Description
`window.cbGetWishlistPageUrl()`	URL of the wishlist page
`window.cbRenderWishlistToast(message, variant, options)`	Shows a toast. `options`: `{ duration, actionLabel, actionHref }`
`window.cbFormatMoney(amount, currency)`	Formats a price with the shop’s money format
`window.cbOpenWishlistInPage(id)`	On the wishlist page, opens a wishlist without reloading

Debugging

Run these in the browser console on your storefront:

// Placement report: are features loaded, how many cards were found, how many icons exist
window.checkWishlistStatus();

// Why does this button point at this variant?
window.cbWhyVariant(document.querySelector('.cb-wishlist-btn'));

// Log every variant change the app detects
window.cbTraceVariant(true);

Storage the app uses

Key	Where	Purpose
`sessionId`	localStorage	Guest identity
`cb_wishlist_customer_id`	localStorage	Detects when another customer logs in
`cb_guest_claimed:<customer>:<session>`	localStorage	Marks a guest wishlist as moved to the customer
`cb_guest_wishlist_blocked:<shop>`	localStorage	Hides “Create” early when guests are blocked
`cbRecentWishlist:1:<shop>:…`	localStorage	Drawer cache (10 minutes)
`recentlyViewedProducts`	localStorage	Recently viewed swatches
`cbwishlist_email_ref`	Cookie, 48 hours	Credits a later order to a reminder email click

Theme integration

Integrations

Events

`cb:wishlists-changed`

`cb:variant-changed`

`cb:wishlist-view-changed`

Cart events

Re-scanning after AJAX updates

Useful globals

Identity and settings

Wishlist mode and guests

UI helpers

Debugging

Storage the app uses

​Events

​cb:wishlists-changed

​cb:variant-changed

​cb:wishlist-view-changed

​Cart events

​Re-scanning after AJAX updates

​Useful globals

​Identity and settings

​Wishlist mode and guests

​UI helpers

​Debugging

​Storage the app uses

Events

`cb:wishlists-changed`

`cb:variant-changed`

`cb:wishlist-view-changed`

Cart events

Re-scanning after AJAX updates

Useful globals

Identity and settings

Wishlist mode and guests

UI helpers

Debugging

Storage the app uses