API

init

Description

Authenticates with the SPREEAI API and returns an SDK object used to render try-on and sizing buttons. The auth handshake happens once per page, regardless of how many buttons you render. Returns null if authentication fails.

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

Parameters

InitOptions

Property	Type	Default	Description
clientId	string	-	Required. Your client id.
partnerId	string	-	Required. The partner id provided to you.
baseURL	string	"https://protea-bridge.spreeai.com"	Optional base URL for the try-on experience.
baseApiURL	string	"https://api.spreeai.com"	Optional base API URL.

Returns

The returned SDK exposes:

interface SpreeAISDK {
  renderTryOnButton(options: RenderTryOnButtonOptions): Promise<void>;
  renderSizingButton(
    options: RenderSizingButtonOptions,
  ): Promise<SizingButtonResult | undefined>;
}

sdk.renderTryOnButton

Description

Renders a try-on button into the element identified by elementId. Clicking the button launches SPREEAI's try-on experience as an overlay for the specified garment(s).

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 multiple. Overridden by features.tryOnButton.text.
enableAddToCart	boolean	false	Optional flag to enable add-to-cart functionality inside the iframe.
features	TryOnFeatures	-	Optional features configuration for loading screen and button styling.
events	TryOnButtonEvents	-	Optional event handlers for button interactions.
variant	VariantOptions	-	Deprecated. Legacy single-garment variant filter. Use garments[i].variant instead.

You must provide exactly one of garments (recommended) or garmentId (deprecated).

GarmentInput

Property	Type	Default	Description
garmentId	string	-	Required. The id of the garment.
variant	VariantOptions	-	Optional variant filter to pin a specific variant.

interface GarmentInput {
  garmentId: string;
  variant?: {
    color?: string;
    fit?: string;
    gender?: string;
    style?: string;
  };
}

If variant is supplied, the matching variant on the garment must exist and be available, or the call exits with an error.

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.

TryOnFeatures

Property	Type	Default	Description
loadingScreen	LoadingScreenConfig	-	Configuration for the loading screen.
tryOnButton	TryOnButtonConfig	-	Configuration for the try-on button styling.

LoadingScreenConfig

Property	Type	Default	Description
videoUrl	string	-	URL to a video to display on the loading screen.
loadingText	string[]	-	Array of text messages to cycle through while loading. Must contain 2–5 strings, each with a maximum of 42 characters. Invalid values are dropped with a console warning and the default loading screen text is shown instead.

TryOnButtonConfig

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 iframe 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.

sdk.renderSizingButton

Description

Renders a sizing-recommendation button into the element identified by elementId. Clicking the button opens a size-recommendation flow. The recommended size is cached in localStorage per garment and is returned (populated from cache) on subsequent loads.

const result = await sdk.renderSizingButton({
  elementId: string,
  garmentId: string,
});

Parameters

RenderSizingButtonOptions

Property	Type	Default	Description
elementId	string	-	Required. The id of the host element used to render the sizing button.
garmentId	string	-	Required. The id of the garment.

Returns

interface SizingButtonResult {
  recommendedSize: string | undefined;
}

Returns { recommendedSize } — populated from cache on subsequent loads, or undefined if no recommendation has been made yet.

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 iframe 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>
  <body>
    <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"
    />
    <div id="try-on-button"></div>
    <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: "your-garment-id",
        });
      }
    </script>
  </body>
</html>

Complete Example

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

const sdk = await init({
  clientId: "client_id",
  partnerId: "my-brand",
});

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,
    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: {
      loadingScreen: {
        videoUrl: "https://cdn.example.com/loading.mp4",
        loadingText: [
          "Preparing your fitting room…",
          "Loading models…",
          "Almost ready!",
        ],
      },
      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 RenderTryOnButtonOptions,
  type GarmentInput,
  type AddToCartClickedEvent,
} from "@spreeai/web-sdk";

tryOnButton (deprecated)

The v1 entry point still works in 2.x but is deprecated and will be removed in v3.0.0. The first call logs a deprecation warning. 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",
  elementId: "try-on-button",
  garmentId: "garment-123",
});