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

# Launch Modes

> Control what each click opens: Sandbox, PDP, Bundle, Share, Flow, or Instant Mode.

Every launcher element decides its own launch mode from the attributes on that exact clicked element. This page covers each mode and the order they're resolved in.

## Resolution order

When a launcher is clicked, Hemsy picks the launch mode by checking, in order:

1. **Instant** — the script tag has `data-hemsy-mode="instant"` **and** the element has `data-hemsy-model`.
2. **Share** — the element has `data-hemsy-share`.
3. **Product** — the element has `data-hemsy-auto-product-context="true"`.
4. **Bundle** — the element has `data-hemsy-closet`.
5. **Sandbox** — none of the above; opens the full experience blank.

`data-hemsy-flow` composes with any mode: it adds a guided flow to whatever launch was resolved. A flow-only launcher opens Sandbox mode with the flow applied.

`data-hemsy-action` (checkout vs cart) is independent of launch mode — it only changes what the final CTA does. See [Checkout vs Cart](/embeds/checkout-vs-cart).

## Launcher attributes

| Attribute                         | Example         | Description                                                                                                  |
| --------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
| `data-hemsy-share`                | `"FreyjHz4"`    | Opens a previously shared look by its short ID.                                                              |
| `data-hemsy-auto-product-context` | `"true"`        | Auto-builds a product payload from the current PDP variant. Falls back to Sandbox if no variant is detected. |
| `data-hemsy-closet`               | `"eyJwcm9k..."` | Explicit URL-safe base64 product payload. Use for Bundle mode.                                               |
| `data-hemsy-flow`                 | `"<flowId>"`    | Adds a guided flow to the launch. Must be on the clicked element.                                            |
| `data-hemsy-model`                | `"<modelId>"`   | Model UUID for Instant mode. Only takes effect when the script has `data-hemsy-mode="instant"`.              |

## Sandbox

The default. No launcher attributes needed — the shopper starts blank and builds a look from your full catalog.

```html theme={null}
<a class="hemsy-launcher" href="#">Design a look</a>
```

## Product context (PDP)

Launch with the product the shopper is currently viewing. Hemsy reads the selected variant from the page (the add-to-cart form or a `?variant=` URL parameter) and pre-loads it.

```html theme={null}
<button class="hemsy-launcher" data-hemsy-auto-product-context="true">
  Try with this product
</button>
```

If no variant can be detected, the launcher falls back to Sandbox mode.

## Bundle

Pre-load one or more specific products — curated looks, bundles, or campaign selections — with an explicit payload on `data-hemsy-closet`.

```html theme={null}
<button class="hemsy-launcher" data-hemsy-closet="YOUR_URLSAFE_BASE64_PAYLOAD">
  Try on Bed Bundle
</button>
```

The payload is a URL-safe base64 encoding of a JSON object listing products:

```json theme={null}
{
  "products": [
    {
      "variantId": 1234567890,
      "attributes": [{ "key": "_bundleTitle", "value": "Starter Bundle" }]
    }
  ]
}
```

<Note>
  The attribute is named `data-hemsy-closet` for historical reasons — a "closet"
  payload is how Bundle mode describes its products. The same payload format
  powers `?closet=` deep links.
</Note>

For the full payload schema, bundle attribute keys (`_bundleId`, `_uniqueId`, and friends), encoding helpers, and a validation checklist, see [Deep Links](/deep-links#closet--structured-payload). Always wrap `data-hemsy-closet` values in quotes.

## Share

Open a previously shared look by its short ID — useful for marketing campaigns, emails, or featuring shopper-created looks on your storefront.

```html theme={null}
<button class="hemsy-launcher" data-hemsy-share="FreyjHz4">
  View Shared Look
</button>
```

Share IDs are generated by Hemsy's in-app Share feature; you don't construct them yourself.

<Warning>
  Share launchers do not work when the embed script has
  `data-hemsy-mode="instant"` — the share parameter is dropped for the whole
  embed instance, including `?share=` links and programmatic opens. Keep share
  buttons on pages using the default script mode.
</Warning>

## Flow

Add a guided, step-by-step flow to any launch:

```html theme={null}
<button class="hemsy-launcher" data-hemsy-flow="YOUR_FLOW_ID">
  Build a bed
</button>
```

Flows compose with every other mode — a Bundle launcher with `data-hemsy-flow` opens the bundle inside the flow. Copy flow IDs from the dashboard.

## Instant

Instant mode skips model selection and immediately generates a try-on image with a specific model and product payload. The shopper clicks, sees the generation loading state, and lands on the result.

Instant requires **both** pieces:

1. `data-hemsy-mode="instant"` on the **script tag** (page-wide).
2. `data-hemsy-model` **and** `data-hemsy-closet` on the **launcher element**. If either is missing, the instant path is skipped.

```html theme={null}
<script
  src="https://hemsy.ai/hemsy-embed.js"
  data-hemsy-subdomain="your-store-subdomain"
  data-hemsy-selector=".hemsy-launcher"
  data-hemsy-mode="instant"
  defer
></script>

<a
  href="#"
  class="hemsy-launcher"
  data-hemsy-model="YOUR_MODEL_ID"
  data-hemsy-closet="YOUR_URLSAFE_BASE64_PAYLOAD"
>
  See it on a model
</a>
```

### Getting model IDs

Model IDs are UUIDs assigned to each image in your store's model library:

1. Go to your store's **Models** page in the Hemsy dashboard.
2. Hover over any model image.
3. Click the copy icon in the bottom-left corner.

### Instant is page-wide

`data-hemsy-mode="instant"` changes how the whole embed instance builds its launch URLs: only instant parameters are forwarded, and share parameters are stripped.

<Warning>
  On a page with an instant script tag: share launchers, `?share=` auto-open
  links, and `HemsyEmbed.open("share", ...)` all silently fail. If you need both
  instant and share launchers on the same page, load separate script tags.
</Warning>

Instant combines normally with `data-hemsy-action="cart"` if your storefront owns cart state — see [Checkout vs Cart](/embeds/checkout-vs-cart).

## URL auto-open

The embed script watches the page URL for `?share=` and `?closet=` parameters and opens the modal automatically on page load:

```
https://your-store.com/?share=FreyjHz4
https://your-store.com/?closet=eyJwcm9kdWN0cy...
```

This powers share links (recipients see the look immediately) and marketing campaigns (pre-load products from ads or emails). The parameter is removed from the URL after opening so a refresh doesn't re-trigger it. For SPAs, the script also intercepts `history.pushState` to catch client-side navigations.

<Note>
  Under an instant script tag, `?share=` auto-open does not work (share is
  stripped), and `?closet=` opens a normal Bundle launch rather than instant
  generation, since no model ID is present in the URL.
</Note>

For constructing these URLs, see [Deep Links](/deep-links).