@simplersuite/wishlist-react

React SDK for SimplerSuite Wishlist — add wishlist functionality to any headless Shopify storefront (Hydrogen, Next.js, Remix, Gatsby, etc.).

Installation

npm install @simplersuite/wishlist-react

Quick Start

import { WishlistProvider, WishlistButton, WishlistGrid } from "@simplersuite/wishlist-react";

function App() {
  return (
    <WishlistProvider
      apiBase="https://your-headless-api-url.com"
      storefrontKey="sfk_..."
      customerToken={jwt} // optional — from server-side token exchange
    >
      <WishlistButton productId="123" />
      <WishlistGrid />
    </WishlistProvider>
  );
}

Auth Modes

Customer mode — pass a JWT obtained via server-side token exchange (POST /auth/token with your API key + secret + customer ID):

<WishlistProvider apiBase={apiBase} storefrontKey="sfk_..." customerToken={jwt} />

Guest mode — uses a storefront public key only. Guest IDs are managed automatically via localStorage:

<WishlistProvider apiBase={apiBase} storefrontKey="sfk_..." />

When customerToken transitions from undefined to a value, guest items are automatically merged into the customer's wishlist.

Hooks

| Hook | Returns | |------|---------| | useWishlist() | { items, loading, error, isGuest, count } | | useWishlistActions() | { addItem, removeItem, bulkRemove, refresh } | | useWishlistShare() | { createShareLink, shareUrl, loading } | | useIsWishlisted(productId) | boolean |

Components

All components accept className, style, and a children render prop for full customization. Zero built-in CSS.

• WishlistButton — heart toggle for add/remove
• WishlistGrid — renders wishlist items in a CSS grid
• WishlistItem — single product card
• WishlistCount — displays the wishlist item count
• WishlistShareButton — generates and copies a share link

Documentation

Full docs at simplersuite.co/docs.

License

MIT