Web SDK Integration

Use @spreeai/web-sdk for a custom or headless web storefront.

These examples target the published v3.0.0 package. Call init() once and guard its nullable result. The partner is resolved from clientId; do not pass partnerId to v3 init(). Existing v2 integrations should follow the official upgrade guide before changing versions.

Install

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

Include the SDK stylesheet documented for the installed SDK version.

Initialize and render

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

// Add <div id="spreeai-try-on"></div> to the product page first.
const sdk = await init({ clientId: "your-client-id" });

if (sdk) {
  await sdk.renderTryOnButton({
    elementId: "spreeai-try-on",
    garments: [{ garmentId: "your-garment-id" }],
    enableAddToCart: true,
  });
}

init() returns null when authentication fails. Guard all render calls.

Sizing

v3.0.0 exposes sizing inside the try-on experience, rather than a separate sdk.renderSizingButton() method. For a garment with approved sizing data, enable that flow on the try-on button:

await sdk?.renderTryOnButton({
  elementId: "spreeai-try-on",
  garments: [{ garmentId: "your-garment-id" }],
  enableSizingRecommendation: true,
});

Enable sizing only after the garment data and partner configuration are ready.

Events

The public SDK documents client-side callbacks for the Try-On button and add-to-cart actions. Connect callbacks to the storefront’s existing analytics and cart layers. Do not place customer imagery, credentials, or unnecessary personal data in analytics payloads.

Production guidance

Initialize once per page.
Render only for eligible garments.
Pass stable catalogue identifiers.
Keep client secrets out of browser code.
Test variant changes and route transitions in single-page applications.
Preserve keyboard focus and an accessible label for the entry point.
Validate loading, failure, and unavailable states.
Monitor product-page performance before and after enabling the integration.