Quickstart

The Souldi widget is a lightweight JavaScript snippet that adds an AI-powered “Try On” button to any product page. Souldi handles authentication, photo uploads, and generation behind the scenes — you just drop in the script and point it at a garment. This guide takes you from zero to a working try-on button in three steps.

Install the widget

Add the widget to your store via npm or a CDN script tag.

npm install @souldi/try-on

<script src="https://unpkg.com/@souldi/try-on/dist/widget.umd.js"></script>

The CDN (UMD) build exposes a global VirtualTryOn object on window. If you use a bundler such as Vite or webpack, import the ESM build at dist/widget.mjs instead.

Initialize the widget

Call VirtualTryOn.init(options) once per page load to configure the widget with your publishable key. Calling init() a second time is ignored.

<script>
  VirtualTryOn.init({
    tenantApiKey: 'pk_live_abc123',
  });
</script>

Option	Type	Required	Description
`tenantApiKey`	`string`	Yes	Your publishable API key from the Souldi dashboard. Safe to expose client-side — it’s scoped to your whitelisted domains.
`theme`	`object`	No	Appearance customization. See Customization.
`onGenerationStart`	`function`	No	Called when AI generation begins. Signature: `()`.
`onGenerationSuccess`	`function`	No	Called when the try-on completes. Signature: `(resultUrl: string)`.
`onError`	`function`	No	Called on any error. Signature: `(message: string)`.
`onLogout`	`function`	No	Called after the user logs out. Signature: `()`.

Use your publishable key (pk_live_...) here — never your secret key. The publishable key is safe in client-side code because it only works from the domains you’ve whitelisted in your dashboard.

Add a Try-On button

Call VirtualTryOn.createButton(options) once per product or garment. The button renders into a container element you provide.

<div id="try-on-btn"></div>

<script>
  VirtualTryOn.createButton({
    containerId: 'try-on-btn',
    garmentUrl: 'https://your-cdn.com/images/jacket-flat.png',
    targetImageId: 'product-image', // optional: auto-swaps this <img> with the result
  });
</script>

Option	Type	Required	Description
`containerId`	`string`	Yes	ID of the DOM element where the button renders.
`garmentUrl`	`string`	Yes	Public URL of the garment image to try on.
`targetImageId`	`string`	No	ID of an `<img>` element to auto-swap with the generated try-on result.
`label`	`string`	No	Button text. Defaults to `"Try On"`.
`mode`	`string`	No	`"vto"` (default) for single-garment try-on, or `"oc"` for the outfit combinator.

In "oc" (outfit combinator) mode, the garment is layered onto the user’s previous completed try-on result — so the customer needs to have finished a try-on earlier in the session before an outfit-combinator button can generate.

Events and callbacks

The four callbacks you pass to init() let you hook your own UI and analytics into the try-on lifecycle. The widget stays lightweight and lets your page own the experience.

Callback	Signature	Good for
`onGenerationStart`	`()`	Showing your own loading spinner or skeleton while the AI works.
`onGenerationSuccess`	`(resultUrl: string)`	Storing the result, firing analytics, or rendering the image yourself.
`onError`	`(message: string)`	Surfacing a toast or inline message when something goes wrong.
`onLogout`	`()`	Resetting UI state after the customer signs out.

If you set targetImageId, the widget already swaps that <img> for you on success — use onGenerationSuccess for everything else, like analytics or a “save to favorites” action.

Full example

A complete, copy-paste product page with init, a button, and callbacks wired up:

<!DOCTYPE html>
<html>
  <head>
    <title>My Store</title>
    <script src="https://unpkg.com/@souldi/try-on/dist/widget.umd.js"></script>
  </head>
  <body>
    <div class="product-card">
      <img id="product-image" src="/images/jacket.jpg" alt="Classic Denim Jacket" />
      <h2>Classic Denim Jacket</h2>
      <p>$89.00</p>

      <!-- The try-on button renders here -->
      <div id="try-on-btn"></div>
    </div>

    <script>
      VirtualTryOn.init({
        tenantApiKey: 'pk_live_abc123',
        theme: {
          mode: 'light',
          accentColor: '#4d7c4b',
        },
        onGenerationSuccess: (resultUrl) => {
          console.log('Try-on result:', resultUrl);
        },
        onError: (message) => {
          console.error('Try-on error:', message);
        },
      });

      VirtualTryOn.createButton({
        containerId: 'try-on-btn',
        garmentUrl: 'https://your-cdn.com/images/jacket-flat.png',
        targetImageId: 'product-image',
      });
    </script>
  </body>
</html>

That’s it. When a customer clicks Try On, Souldi handles verification, the photo upload, and AI generation — and the result appears right on your product page.

Next steps

Customization

Match the widget to your brand with theme modes, accent colors, fonts, and more.

Widget Overview

Learn how the widget works and how it keeps customer photos private.

Get Started

Try-On

Catalog Search

Sizes

Events and callbacks

Full example

Next steps

Customization

Widget Overview

​Events and callbacks

​Full example

​Next steps

Customization

Widget Overview

Events and callbacks

Full example

Next steps