How do I build a custom wishlist UI?

You can replace the app’s product buttons or its whole wishlist view with your own, while keeping the app’s storage, merge logic, reports, and reminders. This guide shows both levels of customization and the events that keep your UI in sync.

Available on Silver plans and above (SDK). Start from JavaScript SDK reference for the method signatures.

Level 1: custom buttons, app popup

The common build: your own product page button, the app’s wishlist popup for the list view.

1. In the App Configuration embed, tick Disable automatic product button placement so the app stops injecting buttons.
2. Render your own button per product with the SDK:

document.addEventListener("wishlist-hero-wishlist-sdk-ready", () => {
  window.WishListHero_SDK.InitializeAddToWishListButton({
    ButtonClassElement: "#my-buy-box-heart",
    ProductId: "1234567890123",
    ProductVariantId: "1234567890456",
    ProductLink: "/products/classic-leather-jacket",
    ProductTitle: "Classic Leather Jacket",
    ProductPrice: 189.99,
    ProductImage: "https://cdn.shopify.com/…jpg",
  });
});

3. The app binds the element, tracks its state, and handles clicks. Your CSS owns the look; the app owns the behavior.

For known static markup, skip the call: use class wishlist-hero-custom-button  with data-wlh-*  attributes and let auto binding do it.

Level 2: your own list view

Replace the popup or page with your own rendering:

1. Drive data from the SDK and the document events rather than your own endpoints:

window.WishListHero_SDK.GetWishListItemsFromServer().then((items) => {
  renderYourList(items);
});

document.addEventListener("wishlist-hero-wishlist-updated", () => {
  window.WishListHero_SDK.GetWishListItemsFromServer().then(renderYourList);
});

2. Add and remove with AddWishListItem , DeleteWishListItem , and DeleteAllWishListItems .
3. Open your view from your own launch points, or keep OpenWishList()  for the app’s display mode.
4. When the shopper moves an item to the cart in your UI, call the REST addToCartNotification  so the dashboard insight stays truthful.

The events that matter

Keep what the app gives you

Even at level 2, the app keeps handling:

• Guest to account merge: the merge runs server side at login and your listeners fire with fresh server items
• Reminders eligibility: items saved through your UI trigger price drop and low stock emails exactly like button saves
• Reports and activity: everything flows into the same dashboard and CSV exports

Test the loop

Add an item through your UI, then confirm in order: the header count or badge updates, the Activity page logs the action, and the item appears in the shopper’s list on another device after login. That is the full loop from Verify your installation.