Skip to main content

Try On for the Web using the JavaScript SDK

This document walks you through implementing SPREEAI's try-on experience with the SPREEAI Web SDK for JavaScript on your webpage.

v3 SDK

v3.0.0 lets the try-on experience show each garment's available sizes and price. v3 contains breaking changes: the partnerId option on init() and features.loadingScreen have been removed. See Upgrading to v3.

Before You Start​

Before integrating our JavaScript SDK into your platform you will need the following:

  • A clientId. This can be obtained from our partnerships team during your onboarding process. Your partner account is resolved from the clientId when the SDK authenticates, so you don't pass a partner id to the SDK.
  • A select set of garments to put through our garment ingestion process.

For more information on partnering with us check out our becoming a partner page.

Installation​

Using a package manager

npm install @spreeai/web-sdk@^3
# or
yarn add @spreeai/web-sdk@^3

In the browser, import the ES module build directly from a CDN inside a <script type="module">:

<script type="module">
  import { init } from "https://unpkg.com/@spreeai/web-sdk@3.0.0/dist/@spreeai/web-sdk.js";
</script>

Regardless of your method of installation, include our default styles in your HTML

<link
  rel="stylesheet"
  href="https://unpkg.com/@spreeai/web-sdk@3.0.0/dist/web-sdk.css"
/>

If you install from npm and use a bundler, you can import the stylesheet instead:

import "@spreeai/web-sdk/dist/web-sdk.css";

Quick Start​

Authenticate once with init() and then render as many try-on buttons as you need from the returned SDK object. Add an anchor element for each button you want to render.

<div id="try-on-button"></div>
import { init } from "@spreeai/web-sdk";

const sdk = await init({
  clientId: "your-client-id",
});

if (sdk) {
  await sdk.renderTryOnButton({
    elementId: "try-on-button",
    garments: [{ garmentId: "garment-123" }],
  });
}

init() returns null if authentication fails, so guard your renderTryOnButton calls with an if (sdk) check. Replace clientId with the value provided to you, and replace garmentId with the id of a processed garment that belongs to your partner account.

After clicking the try-on button a pop up launches as an overlay on the web page, allowing users to go through SPREEAI's try-on experience with the selected garment. On desktop the experience opens as a centered sheet anchored to the bottom of the viewport; on screens 744px wide or narrower it opens full screen.

Basic Try On Button Example​

The following full-page example demonstrates how to add the SPREEAI SDK to your webpage and render the try-on button.

<html>
  <head>
    <link
      rel="stylesheet"
      href="https://unpkg.com/@spreeai/web-sdk@3.0.0/dist/web-sdk.css"
    />
  </head>
  <body>
    <!-- The element used as an anchor for your try on button -->
    <div id="try-on-button"></div>

    <!-- Initialize the SDK and render the try on button -->
    <script type="module">
      import { init } from "https://unpkg.com/@spreeai/web-sdk@3.0.0/dist/@spreeai/web-sdk.js";

      const sdk = await init({
        clientId: "your-client-id",
      });

      if (sdk) {
        await sdk.renderTryOnButton({
          elementId: "try-on-button",
          garments: [{ garmentId: "garment-123" }],
        });
      }
    </script>
  </body>
</html>

Sizes and Prices​

These options on renderTryOnButton control what the shopper sees inside the try-on experience. showSizes and showPrices default to off.

  • showSizes: true shows each garment's availableSizes in the experience.
  • showPrices: true shows each garment's price in the experience.
  • defaultUnits sets the starting unit system for measurements in the shopper's try-on profile: "metric" or "imperial".

availableSizes and price are supplied per garment in the garments array, so you can pass the live values from your product page:

await sdk.renderTryOnButton({
  elementId: "try-on-button",
  garments: [
    {
      garmentId: "garment-123",
      price: "$89.00",
      availableSizes: ["XS", "S", "M", "L", "XL"],
    },
  ],
  showSizes: true,
  showPrices: true,
  defaultUnits: "imperial",
});

Outfits​

You can try on multiple garments together by passing more than one entry in the garments array. Each garment can optionally pin a specific variant (color, fit, gender, style).

The SDK looks up an available outfit that contains all of the garments (and matches any variants you pinned). If it finds one, it renders an outfit-style button: a full-width outlined button with a sparkle icon, the label "Try this look" (or your custom button text), the subtitle "Bring the look to life in the virtual fitting room.", and a chevron. If no matching outfit is available, the SDK falls back to the first garment and renders the standard single-garment button.

await sdk.renderTryOnButton({
  elementId: "try-on-button",
  garments: [
    { garmentId: "shirt-123", variant: { color: "blue", fit: "regular" } },
    { garmentId: "pants-456", variant: { color: "indigo" } },
  ],
});

Advanced Usage Example​

The SDK provides several optional features to customize the experience and integrate it seamlessly with your e-commerce workflow.

You can customize the appearance of the try-on button using the features.tryOnButton configuration, which accepts standard CSS properties like backgroundColor, textColor, borderRadius, and more.

For deeper integration, the events object lets you hook into user interactions—use onTryOnButtonClick to track analytics when users initiate a try-on, and onAddToCartClicked to handle add-to-cart functionality with full control over loading states, error handling, and popup dismissal. Set enableAddToCart: true to display the add-to-cart button within the try-on experience. See the API reference for complete documentation of all available options.

import { init } from "@spreeai/web-sdk";

const sdk = await init({
  clientId: "your-client-id",
});

if (sdk) {
  await sdk.renderTryOnButton({
    elementId: "try-on-button",
    garments: [
      {
        garmentId: "shirt-123",
        variant: { color: "blue", fit: "regular" },
        price: "$59.00",
        availableSizes: ["S", "M", "L"],
      },
      {
        garmentId: "pants-456",
        variant: { color: "indigo" },
        price: "$89.00",
        availableSizes: ["30", "32", "34", "36"],
      },
    ],
    enableAddToCart: true, // Optional: Enable add-to-cart functionality
    showSizes: true,
    showPrices: true,
    events: {
      onTryOnButtonClick: (event) => {
        console.log("Try-on button clicked", event);
      },
      onAddToCartClicked: async ({
        garments,
        setIsLoading,
        closePopUp,
        onError,
      }) => {
        // Handle add to cart
        setIsLoading(true);
        try {
          await fetch("/api/cart/add", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ ids: garments.map((g) => g.id) }),
          });
          setIsLoading(false);
          closePopUp();
        } catch (error) {
          setIsLoading(false);
          onError(error.message);
        }
      },
    },
    features: {
      tryOnButton: {
        text: "Virtual Try On",
        iconUrl: "https://example.com/icon.png",
        iconHeight: "20px",
        backgroundColor: "#000000",
        textColor: "#FFFFFF",
        borderRadius: "8px",
        fontSize: "16px",
        fontWeight: "600",
        padding: "12px 24px",
        border: "none",
        boxShadow: "0 4px 6px rgba(0, 0, 0, 0.1)",
        width: "100%",
      },
    },
  });
}

Upgrading to v3​

v3.0.0 contains the following breaking changes. Update your integration before moving to @spreeai/web-sdk@3.

Change in v3What to do
init() no longer accepts partnerId.Remove partnerId from your init() call. The partner is resolved from your clientId. TypeScript projects will report partnerId as an unknown property.
features.loadingScreen (and the LoadingScreenConfig type) has been removed.Remove features.loadingScreen. The try-on experience uses the SPREEAI loading screen.
The default baseURL changed from https://protea-bridge.spreeai.com to https://vton.spreeai.com.No action if you use the default. If you set baseURL explicitly, confirm the value with SPREEAI. If you restrict origins (for example with a Content Security Policy frame-src directive), allow https://vton.spreeai.com.
The try-on dialog now opens as a bottom-anchored sheet up to 1000px wide and 95% of the viewport height, and full screen at 744px wide or narrower. In v2 it was a 640px drawer on the right.If you override .try-on-dialog styles, re-check them against the new layout.
// v2
const sdk = await init({ clientId, partnerId });

if (sdk) {
  await sdk.renderTryOnButton({
    elementId: "try-on-button",
    garments: [{ garmentId: "garment-123" }],
    features: {
      loadingScreen: { videoUrl, loadingText },
      tryOnButton,
    },
  });
}

// v3
const sdk = await init({ clientId });

if (sdk) {
  await sdk.renderTryOnButton({
    elementId: "try-on-button",
    garments: [{ garmentId: "garment-123" }],
    features: {
      tryOnButton,
    },
  });
}

garments, events, features.tryOnButton, className, button, enableAddToCart, and defaultUnits work the same way in v3.

Migration from v1​

v1's single tryOnButton({...}) call is replaced by an init() step plus a renderTryOnButton call per button. The auth handshake now happens once instead of per-button.

// v1 (deprecated)
import { tryOnButton } from "@spreeai/web-sdk";

await tryOnButton({
  clientId,
  partnerId,
  elementId: "try-on-button",
  garmentId: "garment-123",
  events,
  features,
});

// v3
import { init } from "@spreeai/web-sdk";

const sdk = await init({ clientId });

await sdk?.renderTryOnButton({
  elementId: "try-on-button",
  garments: [{ garmentId: "garment-123" }],
  events,
  features,
});

events, features.tryOnButton, className, button, and enableAddToCart carry over with the same shape. The onAddToCartClicked event payload exposes garments (array) instead of a single garment to support multi-garment outfits.

The legacy tryOnButton entry point is still exported in 3.x and logs a deprecation warning on its first call. It supports only a single garmentId and none of the v2 or v3 options, and it will be removed in a future major release.