> ## Documentation Index
> Fetch the complete documentation index at: https://swish.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Wishlist

> Let customers save products and pick up where they left off across devices.

The wishlist feature lets customers save products to their account so they can find them later. Saved items sync across devices and persist between sessions.

## Add a save button

Use HTML attributes or JavaScript to add a save/unsave toggle to any page.

> [tab] Custom element
>
> Wrap your save button in `<swish-save>` and tell it where to read the product from. `context="pdp"` resolves from the current URL and watches SPA navigation; `context="product-card"` walks to the nearest product link in the surrounding card and watches its href. Mark conditional children with `data-swish-when` - the SDK toggles their visibility based on the parent's `state` attribute.
>
> ```html theme={null}
> <!-- On a product detail page -->
> <swish-save context="pdp">
>   <button type="button">
>     <span data-swish-when="unsaved">Save</span>
>     <span data-swish-when="saved,saving" hidden>Saved</span>
>   </button>
> </swish-save>
>
> <!-- Inside a product card on a collection page -->
> <swish-save context="product-card">
>   <button type="button">
>     <span data-swish-when="unsaved">Save</span>
>     <span data-swish-when="saved,saving" hidden>Saved</span>
>   </button>
> </swish-save>
> ```
>
> When the rendered DOM doesn't carry the product reference, pass `product` and `variant` attributes explicitly. See the [elements reference](https://swish.app/docs/references/sdk/elements.md) for the full attribute set.

> [tab] Placement
>
> Declare placements in `SwishOptions` to automatically mount save buttons. Swish resolves product context from the page URL or element attributes.
>
> **Product detail** - inline with the product form:
>
> ```js theme={null}
> window.SwishOptions = {
>   placements: [
>     {
>       id: "pdp-save-button",
>       target: { selector: ".product-form" },
>       mount: { mode: "after" },
>       element: { name: "save-button" },
>       layout: { type: "inline" },
>     },
>   ],
> };
> ```
>
> **Collections** - overlay on product cards:
>
> ```js theme={null}
> window.SwishOptions = {
>   placements: [
>     {
>       id: "collection-save-button",
>       target: { selector: ".product-card" },
>       mount: { mode: "append" },
>       element: { name: "save-button" },
>       layout: { type: "overlay", anchor: "top-right", offset: { x: 8, y: 8 } },
>     },
>   ],
> };
> ```
>
> See [Placements](https://swish.app/docs/guides/customize/placements/overview.md) for the full configuration reference.

> [tab] React
>
> Use the `useSwishItem` hook to build a custom save button.
>
> ```tsx theme={null}
> import { useSwishItem } from "@swishapp/react";
>
> function SaveButton({ productId }: { productId: string }) {
>   const { saved, toggle, loading } = useSwishItem({ productId });
>
>   return (
>     <button type="button" onClick={toggle} disabled={loading}>
>       {saved ? "Saved" : "Save"}
>     </button>
>   );
> }
> ```
>
> You can also pass a `variantId` to save a specific variant:
>
> ```tsx theme={null}
> const { saved, toggle } = useSwishItem({ productId, variantId });
> ```

More patterns, including a custom wishlist page, are on the [SDK examples](https://swish.app/docs/references/sdk/examples.md) page.

## Configuration options

Control how the save and unsave flows behave by passing intent options to the SDK configuration.

### Save behavior

Set these under `intents.saveProduct` in your SDK options:

| Option | Type | Default | Description |
| - | - | - | - |
| `promptVariantIfMissing` | `boolean \| function` | `true` | Show a variant selector when no variant is provided. Pass a function to decide per product. |
| `promptVariantIfPresent` | `boolean` | `false` | Show a variant selector even when a variant is already selected. |
| `saveBeforeVariantPrompt` | `boolean` | `true` | Save the item immediately, then show the variant selector. Selecting a variant updates the saved item. Dismissing leaves the item saved without a variant. |
| `showFeedback` | `boolean` | `true` | Show a toast notification after saving. |

```js theme={null}
window.SwishOptions = {
  // ...
  intents: {
    saveProduct: {
      promptVariantIfMissing: true,
      saveBeforeVariantPrompt: true,
    },
  },
};
```

### Unsave behavior

Set these under `intents.unsaveProduct`:

| Option | Type | Default | Description |
| - | - | - | - |
| `selectList` | `boolean` | `true` | Let the customer choose which list to remove the item from. |
| `confirm` | `boolean` | `true` | Show a confirmation dialog before removing. |
| `showFeedback` | `boolean` | `true` | Show a toast notification after removing. |

> [!NOTE]
>
> For the full list of intent options, see the [SDK configuration
> reference](https://swish.app/docs/references/sdk/configuration.md#intents).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.