What the Wishlist Heart is
The wishlist heart is a small button you can drop onto product cards and product pages so shoppers can save items to their Mage wishlist with one click. It fills in when the product (or selected variant) is on the customer's wishlist and unfills when it's removed.
There are two parts to setting it up:
Customize how it looks in the Mage admin.
Add it to your theme by placing a small snippet wherever you want the heart to appear.
Before you start
Prerequisite
The Mage app embed must be enabled in your theme for the heart button to render. In your Shopify admin go to Online Store → Themes → Customize → App embeds and make sure Mage Loyalty is toggled on.
Customize the appearance
In your Mage Loyalty admin, go to Loyalty Pages → Wishlist Heart. You'll see a live preview on the right while you edit.
Appearance
Active colour — the fill/stroke when the product is wishlisted.
Inactive colour — the stroke when the product is not wishlisted.
Icon size — heart width and height (16–64 px).
Show circle background — render the heart inside a circular container. Useful when overlaying on product images. Set the circle colour and padding (0–32 px) once enabled.
Advanced
Disable Customizer Styles — removes all inline styles so the heart relies entirely on your custom CSS.
Custom CSS — drop in your own rules using the
.mage-wishlist-heart__*classes and--mage-heart-*variables. See the reference table below.
Click Save when you're done. Changes apply to every heart on your storefront immediately.
Heart Button Setup
To make hearts appear on your storefront, you need to add a small snippet wherever you want one to show up. You can do this two ways.
Snippets
Product card (collection pages, search results, featured products)
<mage-wishlist-heart product-id="{{ product.id }}"></mage-wishlist-heart>Fills when any variant of the product is on the wishlist.
Product page (with variant picker)
<mage-wishlist-heart product-id="{{ product.id }}" variant-id="{{ product.selected_or_first_available_variant.id }}"></mage-wishlist-heart>Fills only for the selected variant.
Tip
When the Product Page snippet is used, the heart automatically adapts to the customer's currently selected variant — switching states as they change colour, size, etc.
Option 1: Add via the Theme Customizer (no code)
This is the easiest option if your theme supports adding blocks to product cards or product pages.
Go to Online Store → Themes → Customize.
Open the page you want to add the heart to (e.g. a collection page for the product card, or a product page).
Click Add block or Add section inside the product card / product information area and choose Custom Liquid.
Paste the relevant snippet from above into the Custom Liquid box.
Drag the block to where you want the heart to appear and click Save.
Note
Not every theme exposes a Custom Liquid block on product cards. If you can't find one, use Option 2 below.
Option 2: Add by editing the theme code
Use this option if your theme doesn't support Custom Liquid blocks in the right place, or you want full control over where the heart sits.
Go to Online Store → Themes and click the ⋯ menu next to your live theme, then Edit code.
For the product card, open the file that renders product cards (commonly
snippets/card-product.liquidor similar in your theme).For the product page, open the main product section (commonly
sections/main-product.liquid).Paste the appropriate snippet from above where you want the heart to appear.
Click Save.
Tip
We recommend duplicating your theme before editing code, so you can roll back easily if something looks off.
Handling products with variants
If your products come in variants such as colours or sizes, it helps to understand how the heart decides when to look "saved". This matters most when a shopper saves one variant on the product page, then sees the same product on a collection card that is showing a different variant.
The scenario
Imagine you sell a t-shirt in Red, Blue, and Green. A shopper opens the product page, chooses Blue, and taps the heart to save it. Later they browse your homepage, where the same t-shirt appears on a card showing the default colour, Red.
By default, a heart that is tied to a specific variant only fills for that exact variant. So the shopper saved Blue, the card is showing Red, and the heart looks empty even though they have already saved this product. That can be confusing for shoppers.
There are two simple ways to handle this. Pick whichever fits how your store works.
Option A: Fill the heart if any variant is saved
Add data-match="product" to your product-card heart:
<mage-wishlist-heart product-id="{{ product.id }}" variant-id="{{ product.selected_or_first_available_variant.id }}" data-match="product"></mage-wishlist-heart>Now the card's heart fills whenever the shopper has saved any variant of that product, whether that was Red, Blue, or Green.
Tapping an empty heart saves the variant currently shown on the card (for example Red).
Tapping a filled heart removes the product from the wishlist completely, including every variant of it the shopper had saved.
Leave your Product Page heart as it is, without data-match, so on the product page the heart still reflects the exact variant the shopper is viewing.
Best for
Stores whose product cards show a specific variant, and that want that colour or size recorded when a shopper saves straight from the card, while still showing the heart as saved for any variant.
Option B: Use only a product ID on the card
Alternatively, give your card heart only a product-id and no variant-id:
<mage-wishlist-heart product-id="{{ product.id }}"></mage-wishlist-heart>A heart with no variant always fills when any variant of the product is saved, so it solves the same problem without any extra attribute however you only save the product at a product-level rather than at a variant-level. Here is how it works together with your product page:
If a shopper saves from the card first, the product is saved without a specific variant.
When they later choose a variant on the product page and save it, that specific variant replaces the general save.
Either way the card heart stays filled, and the wishlist ends up holding the exact variant once the shopper picks one.
Best for
Stores that prefer to keep product cards simple and let shoppers choose the exact variant later on the product page.
CSS classes & variables reference
If you're using the custom CSS field (or styling from your theme stylesheet), these are the targets the heart exposes.
Selector / Variable | What it targets |
| The custom element wrapper. |
| The button itself. |
| The button when the item is on the wishlist. |
| The button when it includes accompanying text. |
| The heart icon (SVG). |
| The label text next to the heart. |
| Active (filled) colour. |
| Inactive (unfilled) colour. |
| Width and height of the heart icon. |
| Background colour of the circle (when enabled). |
| Padding inside the circle. |
| Corner radius of the circle. |
Still need help? Reach out to the Mage Loyalty team through our live chat support.