API

This reference covers @spreeai/web-sdk v3.x. Upgrading from v2? See Upgrading to v3.

init

Description

Authenticates with the SPREEAI API and returns an SDK object used to render try-on buttons. The auth handshake happens once per page, regardless of how many buttons you render. Your partner account is resolved from the clientId during authentication. Returns null if clientId is missing or authentication fails; the reason is logged to the console.

const sdk = await init({
  clientId: string,
  baseURL?: string,    // default: "https://vton.spreeai.com"
  baseApiURL?: string, // default: "https://api.spreeai.com"
});

Parameters

InitOptions

Property	Type	Default	Description
clientId	string	-	Required. Your client id.
baseURL	string	"https://vton.spreeai.com"	Optional base URL for the try-on experience.
baseApiURL	string	"https://api.spreeai.com"	Optional base API URL.

note

partnerId is no longer an init() option as of v3.0.0. Remove it from existing integrations.

Returns

Promise<SpreeAISDK | null>. The returned SDK exposes:

interface SpreeAISDK {
  renderTryOnButton(options: RenderTryOnButtonOptions): Promise<void>;
}

sdk.renderTryOnButton

Description

Renders a try-on button into the element identified by elementId, replacing any existing content in that element. Clicking the button launches SPREEAI's try-on experience as an overlay for the specified garment(s).

Before rendering, the SDK validates the garments. If validation fails, no button is rendered and the reason is logged to the console. See Garment validation.

Parameters

RenderTryOnButtonOptions

Property	Type	Default	Description
elementId	string	-	Required. The id of the host element used to render the try-on button.
garments	GarmentInput[]	-	Required (one of). Array of garments to try on. 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.
garmentId	string	-	Required (one of). Deprecated. Single garment id. Use garments instead.
className	string	-	Optional extra CSS class on the button element.
button	{ text?: string }	-	Optional button label. Default: "Try It On" for a single garment, "Try this look" for an outfit. Overridden by features.tryOnButton.text.
enableAddToCart	boolean	false	Optional flag to enable add-to-cart functionality inside the try-on experience.
showSizes	boolean	false	Optional flag to show each garment's availableSizes in the try-on experience.
showPrices	boolean	false	Optional flag to show each garment's price in the try-on experience.
defaultUnits	"metric" | "imperial"	-	Optional default unit system for measurements in the shopper's try-on profile.
features	TryOnFeatures	-	Optional features configuration for button styling.
events	TryOnButtonEvents	-	Optional event handlers for button interactions.
variant	VariantOptions	-	Deprecated. Legacy single-garment variant filter, used only with garmentId. Use garments[i].variant instead.

Provide garments (recommended) or garmentId (deprecated). If both are provided, a non-empty garments array takes precedence.

GarmentInput

Property	Type	Default	Description
garmentId	string	-	Required. The id of the garment.
variant	VariantOptions	-	Optional variant filter to pin a specific variant.
price	string	-	Optional display price, shown as-is (for example "$89.00"). Displayed when showPrices is true.
availableSizes	string[]	-	Optional list of sizes in stock (for example ["S", "M", "L"]). Displayed when showSizes is true.

interface GarmentInput {
  garmentId: string;
  variant?: {
    color?: string;
    fit?: string;
    gender?: string;
    style?: string;
  };
  price?: string;
  availableSizes?: string[];
}

VariantOptions

Property	Type	Default	Description
color	string	-	Pin the garment variant by color.
fit	string	-	Pin the garment variant by fit.
gender	string	-	Pin the garment variant by gender.
style	string	-	Pin the garment variant by style.

Variant values are matched case-insensitively. For color, the value is matched against the variant's color name (for example "blue"), not its hex code.

TryOnFeatures

Property	Type	Default	Description
tryOnButton	TryOnButtonConfig	-	Configuration for the try-on button styling.

note

features.loadingScreen was removed in v3.0.0. The try-on experience uses the SPREEAI loading screen.

TryOnButtonConfig

Each style value is applied as an inline style on the button element, so it overrides the default stylesheet.

Property	Type	Default	Description
text	string	-	Custom text to display on the button.
iconUrl	string	-	URL to a custom icon to display on the button.
iconHeight	string	-	Height of the icon (e.g., "20px").
borderRadius	string	-	Border radius of the button (e.g., "8px").
backgroundColor	string	-	Background color of the button (e.g., "#000000").
textColor	string	-	Text color of the button (e.g., "#FFFFFF").
width	string	-	Width of the button (e.g., "100%").
height	string	-	Height of the button.
fontSize	string	-	Font size of the button text (e.g., "16px").
fontWeight	string	-	Font weight of the button text (e.g., "600").
padding	string	-	Padding inside the button (e.g., "12px 24px").
border	string	-	Border style of the button (e.g., "none").
boxShadow	string	-	Box shadow of the button.

TryOnButtonEvents

Property	Type	Default	Description
onTryOnButtonClick	(event: TryOnButtonClickEvent) => void	-	Callback fired when the try-on button is clicked, before the dialog opens.
onAddToCartClicked	(event: AddToCartClickedEvent) => void	-	Callback fired when the try-on experience posts an add-to-cart message. Requires enableAddToCart: true.

TryOnButtonClickEvent

Property	Type	Default	Description
name	string	"spreeai-try-on-button-clicked"	The name of the event.

AddToCartClickedEvent

Property	Type	Default	Description
name	string	"spreeai-add-to-cart-clicked"	The name of the event.
garments	Garment[]	-	The garments the user wants to add to cart.
setIsLoading	(loading: boolean) => void	-	Function to set the loading state of the button.
closePopUp	() => void	-	Function to close the try-on popup.
onError	(message: string) => void	-	Function to display an error message.

Garment

Property	Type	Default	Description
id	string	-	Required. The unique identifier of the garment.
partner_id	string	-	Required. The partner ID associated with the garment.
available	boolean	-	Required. Whether the garment is available.
name	string	-	Required. The name of the garment.
description	string	-	Optional description of the garment.

Garment validation

renderTryOnButton checks the garments before it renders anything:

• Single garment. The garment must exist, belong to your partner account, and be available for try-on. If you pinned a variant and the garment has variants, a matching variant must exist and be available.
• Outfit (two or more garments). The SDK looks up an available outfit that contains all of the garments, where every garment is available and every pinned variant matches. If one exists, the SDK renders the outfit button. If not, it validates only the first garment using the single-garment rules and renders a single-garment button for it.

If validation fails, the button isn't rendered and the reason is logged to the console.

Button styles

The SDK renders one of two button styles, depending on the validated garments:

Style	When	CSS class	Default label
Single garment	One garment, or an outfit fallback	try-on-button	"Try It On"
Outfit	Two or more garments forming an outfit	try-on-outfit-button	"Try this look"

The outfit button is full width and outlined, with a sparkle icon, a fixed subtitle ("Bring the look to life in the virtual fitting room."), and a chevron. Use className or features.tryOnButton to adjust either style.

Events

onTryOnButtonClick

Fired when the user clicks the try-on button, before the dialog opens.

{
  name: "spreeai-try-on-button-clicked";
}

onAddToCartClicked

Fired when the try-on experience posts an add-to-cart message. Requires enableAddToCart: true.

{
  name: "spreeai-add-to-cart-clicked",
  garments: Garment[],          // garments the user wants to add
  setIsLoading: (loading: boolean) => void,
  closePopUp: () => void,
  onError: (message: string) => void,
}

events: {
  onAddToCartClicked: async ({ garments, setIsLoading, closePopUp, onError }) => {
    setIsLoading(true);
    try {
      await fetch("/api/cart", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ ids: garments.map((g) => g.id) }),
      });
      setIsLoading(false);
      closePopUp();
    } catch (err) {
      setIsLoading(false);
      onError("Failed to add to cart. Please try again.");
    }
  },
}

Basic Usage

<html>
  <head>
    <link
      rel="stylesheet"
      href="https://unpkg.com/@spreeai/web-sdk@3.0.0/dist/web-sdk.css"
    />
  </head>
  <body>
    <div id="try-on-button"></div>
    <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: "your-garment-id" }],
        });
      }
    </script>
  </body>
</html>

Complete Example

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

const sdk = await init({
  clientId: "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"],
      },
    ],
    enableAddToCart: true,
    showSizes: true,
    showPrices: true,
    defaultUnits: "metric",
    events: {
      onTryOnButtonClick: (event) => analytics.track("try_on_started", event),
      onAddToCartClicked: async ({
        garments,
        setIsLoading,
        closePopUp,
        onError,
      }) => {
        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 (err) {
          setIsLoading(false);
          onError(err.message);
        }
      },
    },
    features: {
      tryOnButton: {
        backgroundColor: "#000",
        textColor: "#fff",
        borderRadius: "4px",
        fontSize: "14px",
        padding: "10px 20px",
      },
    },
  });
}

TypeScript Support

The SDK is written in TypeScript and ships full type definitions:

import {
  init,
  type SpreeAISDK,
  type InitOptions,
  type RenderTryOnButtonOptions,
  type GarmentInput,
  type VariantOptions,
  type TryOnFeatures,
  type TryOnButtonEvents,
  type AddToCartClickedEvent,
} from "@spreeai/web-sdk";

Removed in v3

API	Replacement
init({ partnerId })	None. The partner is resolved from clientId.
features.loadingScreen / LoadingScreenConfig	None. The try-on experience uses the SPREEAI loading screen.

tryOnButton (deprecated)

The v1 entry point is still exported in 3.x but is deprecated and will be removed in a future major release. The first call logs a deprecation warning. It supports a single garmentId only, authenticates on every call, and doesn't support garments, variants, sizes, or prices. New integrations should use init plus sdk.renderTryOnButton instead.

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

await tryOnButton({
  clientId: "your-client-id",
  partnerId: "your-partner-id", // ignored, but still required by the TypeScript type
  elementId: "try-on-button",
  garmentId: "garment-123",
});