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 Wishlist and click Customise on Wishlist Heart (it is also under Loyalty Pages). The builder opens full screen, with your settings on the left and a live preview of the heart on a sample product card on the right.
Use the bar at the top of the builder to switch the preview between Not in wishlist and In wishlist (clicking the heart in the preview does the same), and between desktop and mobile. You can zoom and move the preview, and undo or redo any change.
Design tab
In wishlist: the colour of the filled heart once the product is on the wishlist.
Not in wishlist: the outline colour of the empty heart.
Icon size: the heart's width and height (16 to 64 px).
Show circle background: puts the heart inside a circle, which helps it stand out over product photos. Once it is on, set the Circle colour and the Padding between the heart and the edge of the circle (0 to 32 px).
Reset to defaults: puts the design settings back to their defaults. Your custom CSS is kept.
Advanced tab
Disable customizer styles: skips the colours and sizes from the Design tab, so the heart's look comes entirely from your custom CSS.
Custom CSS: your own rules using the
.mage-wishlist-heart__*classes and--mage-heart-*variables. See the reference table below.Add to your theme: the snippets for product cards and product pages, ready to copy.
Click Save when you're done. Changes apply to every heart on your storefront immediately.
Ask Mage
On plans that include Mage AI, the builder has an Ask Mage button in the top bar. Describe the change you want in plain words, for example "make the heart red when it's saved" or "put it in a white circle", and Ask Mage updates the settings or the custom CSS for you. Changes show in the preview straight away and stay unsaved until you click Save, and you can undo them.
Ask Mage can also suggest where the snippet could go in your theme. It reads your live theme to make the suggestion, but themes differ and are often customised, so treat it as a starting point and check it on a copy of your theme first.
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.
Important: use the name your product card gives the product
Inside a product card file, the product is not always called product. Dawn and the themes built on it call it card_product, so in snippets/card-product.liquid the snippet must read:
<mage-wishlist-heart product-id="{{ card_product.id }}"></mage-wishlist-heart>With product.id in a file that doesn't define product, the heart gets no product and won't appear. Look at how the rest of the file refers to the product (for example card_product.title) and use the same name.
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
Most themes offer a Custom Liquid block on the product page, but very few offer one inside product cards. For collection pages you will usually need Option 2.
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.
Duplicate your theme first. Go to Online Store → Themes, click the ⋯ menu next to your live theme and choose Duplicate. Make your changes on the copy so you can preview them safely.
On the copy, click ⋯ 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, using the product name the file uses (see the note above).
Click Save, preview the copy, then publish it.
Not sure where it goes?
Every theme is built differently. If you're unsure, or would rather not edit your theme, the Mage team can add it for you. Email [email protected].
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.
To avoid this, give your product-card heart only a product ID.
Use only a product ID on the card
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. The product is then saved 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.
Important
If you use back-in-stock or price-drop alerts, they are only sent for a saved variant. A product with more than one variant that is saved without a specific variant gets neither alert until the shopper saves a variant. Products with a single variant are not affected.
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. The variables are written by the Design tab's settings; to set them yourself in custom CSS, turn on Disable customizer styles first.
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? Email [email protected] or reach out to the Mage Loyalty team through our live chat support.
