JavaScript API

Once the storefront script loads, window.Wishlist exposes a small API. Wait for Wishlist.ready before reading state. Ids are numeric strings; numbers and gid://shopify/Product/<id> strings are accepted as input too.

window.Wishlist.ready.then(() => {
  console.log(Wishlist.count(), "saved products");
});

A TypeScript declaration file, wishlist.d.ts, describes the full API. Copy it into your theme or project to get types for window.Wishlist and the events.

Methods

Method	Returns	Description
`add({ productId, variantId?, listId?, quantity? })`	`Promise<boolean>`	Adds an item. Resolves `false` if a handler cancelled it or it failed.
`remove({ productId, variantId?, listId? })`	`Promise<boolean>`	Removes an item. Without `variantId`, removes every variant. Without `listId`, removes from every list the shopper owns.
`toggle({ productId, variantId?, listId? })`	`Promise<boolean>`	Resolves `true` when the item is now saved.
`has(productId, variantId?)`	`boolean`	Whether the product is saved.
`lists()`	`WishlistList[]`	The shopper's lists.
`items(listId?)`	`Promise<WishlistItem[]>`	Items of one list, or of every list the shopper owns.
`count()`	`number`	Number of distinct saved products.
`open({ listId? })`	`Promise<void>`	Opens the drawer, or goes to the wishlist page.
`close()`	`void`	Closes the drawer.
`on(event, handler)`	`() => void`	Subscribes to an event. Returns an unsubscribe function.
`off(event, handler)`	`void`	Unsubscribes.

Events

Events are available through Wishlist.on() and as DOM events on document. DOM events bubble and are composed, so they cross shadow roots.

`Wishlist.on`	DOM event	Detail
`ready`	`wishlist:ready`	`{ version, productIds, count }`
`change`	`wishlist:change`	`{ version, productIds, count }`
`add`	`wishlist:add`	`{ productId, variantId?, listId? }`
`remove`	`wishlist:remove`	`{ productId, variantId?, listId? }`

document.addEventListener("wishlist:add", (event) => {
  console.log("Saved", event.detail.productId);
});

Wishlist.on("change", ({ count }) => {
  document.querySelector(".my-count").textContent = count;
});

A ready handler registered after the script is ready runs at once.

Changing or cancelling an add

beforeAdd handlers run before every add. They can edit event.detail or cancel the add.

Wishlist.on("beforeAdd", (event) => {
  if (event.detail.productId === "123") event.preventDefault();
});

Debug mode

Add ?wl_debug=1 to any storefront URL to log state changes, requests and events to the browser console. The flag is remembered in this browser until you open a URL with ?wl_debug=0.