Setting the file. One moment.
Skill 01 · Storefront Best Practices
Subchapter 1.16
reference/features/wishlist.mdMarkdown8 KBView on GitHub
A wishlist (also called favorites or save for later) allows customers to save products they’re interested in for future purchase. This feature helps organize shopping, track desired items, and increases return visits and conversions.
Why wishlists matter:
Conversion impact:
CRITICAL: Only implement wishlist UI if your ecommerce backend supports wishlist functionality.
Before implementing:
Medusa users: Medusa core doesn’t include wishlist by default. Install the Wishlist plugin from Medusa examples repository. Plugin provides full wishlist functionality with API endpoints.
General backends: Wishlist typically requires user authentication. API endpoints needed:
If backend doesn’t support wishlist: Don’t implement the feature. localStorage-only wishlist creates poor UX (lost on device switch, no sync, no remarketing).
Heart icon (universal symbol):
Colors:
Product cards: Top-right corner of product image, always visible (not hover-only), 16px margin from edges.
Product detail page: Near “Add to Cart” button, or above product image, or with sharing options. Optional text label: “Add to Wishlist” or icon-only.
Flow:
Optimistic UI: Update icon immediately, revert if API fails. Provides instant feedback.
Error handling: Show error toast (“Failed to add to wishlist”), revert icon to outline, allow retry.
Variant handling: Save specific variant (size, color) if selected on product page. On product cards, save default variant.
From product card/page: Click filled heart → changes to outline → toast: “Removed from wishlist” → update badge (-1).
From wishlist page: X icon in corner of product card or “Remove” button → item fades out. Optional: Undo action in toast (5 seconds).
Confirmation: Generally not needed (low stakes, easily reversible). Only confirm for bulk actions (“Clear all”).
Heading: “My Wishlist” or “Favorites” with item count (“12 items saved”).
Product grid: Similar to product listing page. Product cards with images, titles, current prices (may differ from when added), stock status.
Empty state: “Your wishlist is empty” with “Start Shopping” CTA.
Display per item:
Add to Cart (CRITICAL): “Add to Cart” button on each item. Adds item to cart without removing from wishlist (user may want both). Success toast: “Added to cart”. Don’t navigate away (stay on wishlist page).
Tradeoff:
Stock handling: If out of stock, disable “Add to Cart” and show “Notify me when back in stock” option (if backend supports).
Require login (Recommended):
Why:
Implementation: Click wishlist → Show login prompt modal: “Log in to save your wishlist”. Include “Sign Up” button. Clear benefit: “Save items across all your devices”.
localStorage approach (Not Recommended):
Exception: If backend doesn’t support authenticated wishlist, consider not implementing feature at all rather than localStorage-only.
Position: Top navigation bar, between search icon and cart icon. Or: In user account dropdown menu.
Icon: Heart icon (outline or filled if items in wishlist). 24-32px size, consistent with cart icon.
Badge count: Small circle with number showing total items in wishlist. Red or brand color, positioned top-right of heart icon.
Link behavior: Navigates to wishlist page on click. Dropdown less common for wishlist (unlike cart popup).
Heart button: Larger touch target (44px minimum), positioned in corner of product image, clear tap feedback (scale or color change).
Wishlist page: Single column product grid, stack cards vertically, full-width “Add to Cart” buttons, large remove buttons (44px touch target).
Navigation icon: Heart icon in mobile navbar or hamburger menu, with badge count.
Login prompt: If guest clicks wishlist, show bottom sheet (less disruptive than full modal) with “Log in to save your wishlist” message.
Essential features: