> ## Documentation Index
> Fetch the complete documentation index at: https://codebeans-wishlyst.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript API & events

> Globals, functions and DOM events you can use to integrate Codebeans Wishlyst with your theme's JavaScript.

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.

> [!NOTE]
>
> 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.

```js theme={null}
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.

```js theme={null}
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:

```js theme={null}
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:

```js theme={null}
// 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:

```js theme={null}
// 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.