Try On & Sizing for the Web using the JavaScript SDK

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

v2 SDK

v2.0.0 introduces a new SDK shape: authenticate once with init(), then render any number of try-on or sizing buttons from the returned SDK. The legacy tryOnButton(...) API still works in v2 but is deprecated and will be removed in v3.0.0. See Migration from v1.

Before You Start

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

A unique partner id. This can be obtained from our partnerships team during your onboarding process.
A client_id.
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
# or
yarn add @spreeai/web-sdk

In browser

<script type="module" src="https://unpkg.com/@spreeai/web-sdk@2.1.0"></script>

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

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

Quick Start

In v2 you authenticate once with init() and then render as many 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>
<div id="sizing-button"></div>

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

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

if (sdk) {
  // Render a try-on button for a single garment
  await sdk.renderTryOnButton({
    elementId: "try-on-button",
    garmentId: "garment-123",
    enableAddToCart: true,
  });

  // Render a sizing recommendation button
  await sdk.renderSizingButton({
    elementId: "sizing-button",
    garmentId: "garment-123",
  });
}

init() returns null if authentication fails, so guard your render* calls with an if (sdk) check. Replace clientId and partnerId with the values provided to you, and replace garmentId with the id of a processed garment associated with your partnerId.

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.

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>
    <script type="module" src="https://unpkg.com/@spreeai/web-sdk@2.1.0"></script>
    <link
      rel="stylesheet"
      href="https://unpkg.com/@spreeai/web-sdk@2.1.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 "@spreeai/web-sdk";

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

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

Advanced Usage Example

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

You can try on multiple garments together by passing a garments array. Multi-garment requests are validated as an outfit on the server; if no matching outfit is found, the SDK falls back to the first garment. Each garment can optionally pin a specific variant (color, fit, gender, style).

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. The features.loadingScreen option lets you provide a custom video and rotating text messages to display while the try-on experience loads.

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",
  partnerId: "your-partner-id",
});

if (sdk) {
  await sdk.renderTryOnButton({
    elementId: "try-on-button",
    garments: [
      { garmentId: "shirt-123", variant: { color: "blue", fit: "regular" } },
      { garmentId: "pants-456", variant: { color: "indigo" } },
    ],
    enableAddToCart: true, // Optional: Enable add-to-cart functionality
    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: {
      loadingScreen: {
        videoUrl: "https://example.com/loading-video.mp4",
        loadingText: [
          "Preparing your fitting room...",
          "Loading models...",
          "Almost ready to try on!",
        ],
      },
      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%",
      },
    },
  });
}

Migration from v1

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

// v1 (deprecated — emits a console warning on first call, removed in v3.0.0)
import { tryOnButton } from "@spreeai/web-sdk";

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

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

const sdk = await init({ clientId, partnerId });

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

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

The legacy tryOnButton entry point still works in 2.x. The first call logs a deprecation warning, and it will be removed in v3.0.0.

Before You Start​

Installation​

Quick Start​

Basic Try On Button Example​

Advanced Usage Example​

Migration from v1​