Hooks API

All hooks must be used within a <WishlistProvider>.

useWishlist

Returns the current wishlist state.

import { useWishlist } from "@simplersuite/wishlist-react";

function MyComponent() {
  const { items, loading, error, isGuest, count } = useWishlist();
}

Property	Type	Description
`items`	`WishlistItem[]`	Current wishlist items
`loading`	`boolean`	True during initial fetch
`error`	`Error \| null`	Last error, if any
`isGuest`	`boolean`	True if using guest mode
`count`	`number`	Number of items

useWishlistActions

Returns mutation functions with optimistic updates.

import { useWishlistActions } from "@simplersuite/wishlist-react";

function MyComponent() {
  const { addItem, removeItem, bulkRemove, refresh } = useWishlistActions();

  // Add a product
  await addItem("product_123", {
    variantId: "variant_456",
    metadata: { color: "blue" },
  });

  // Remove a product
  await removeItem("product_123");

  // Remove multiple products
  await bulkRemove(["product_1", "product_2"]);

  // Force refresh from server
  await refresh();
}

Function	Params	Description
`addItem`	`(productId, options?)`	Add to wishlist (optimistic)
`removeItem`	`(productId)`	Remove from wishlist (optimistic)
`bulkRemove`	`(productIds[])`	Remove multiple items
`refresh`	`()`	Re-fetch from server

All mutation functions return a Promise and throw on API failure (after rolling back the optimistic update).

useWishlistShare

Returns sharing functionality.

import { useWishlistShare } from "@simplersuite/wishlist-react";

function ShareButton() {
  const { createShareLink, shareUrl, loading } = useWishlistShare();

  return (
    <button onClick={() => createShareLink()} disabled={loading}>
      {shareUrl ? "Link created!" : "Share Wishlist"}
    </button>
  );
}

Property	Type	Description
`createShareLink`	`() => Promise<string \| null>`	Generate a share URL
`shareUrl`	`string \| null`	Last generated share URL
`loading`	`boolean`	True while generating

useIsWishlisted

O(1) check whether a product is in the wishlist.

import { useIsWishlisted } from "@simplersuite/wishlist-react";

function ProductCard({ productId }) {
  const isWishlisted = useIsWishlisted(productId);

  return <span>{isWishlisted ? "In wishlist" : "Not in wishlist"}</span>;
}