@souldi/try-on

Drop a virtual try-on button into any e-commerce site in under 5 minutes.

Let your customers see how clothes look on them — powered by AI, embedded with a single script tag. No iframes, no redirects, no heavy dependencies.

Quick Start

1. Install

npm install @souldi/try-on

Or load directly via CDN:

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

2. Initialize

<script>
  VirtualTryOn.init({
    apiBaseUrl: 'https://api.yourdomain.com',
    tenantApiKey: 'your_publishable_api_key',
  });
</script>

3. Add a Try-On Button

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

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

That's it. Your customers can now try on clothes with AI.

How It Works

Customer clicks the Try On button
First-time users verify their email (magic link OTP — no passwords)
They upload a photo of themselves
AI generates a realistic try-on image in seconds
The result appears directly on your product page

Returning users skip straight to step 4 — their session and photo are remembered.

Configuration

`init(options)`

Call once per page load to configure the widget.

Option	Type	Required	Description
`apiBaseUrl`	`string`	Yes	Your Souldi API endpoint URL
`tenantApiKey`	`string`	Yes	Your publishable API key (from your Souldi dashboard)
`theme`	`object`	No	Customize the widget appearance (see Theming)
`onGenerationStart`	`function`	No	Called when AI generation begins
`onGenerationSuccess`	`function(resultUrl)`	No	Called with the result image URL on success
`onError`	`function(message)`	No	Called when something goes wrong
`onLogout`	`function`	No	Called when the user logs out

`createButton(options)`

Add a try-on button for a specific garment. Call once per product on the page.

Option	Type	Required	Description
`containerId`	`string`	Yes	ID of the DOM element where the button will render
`garmentUrl`	`string`	Yes	Public URL of the garment image
`targetImageId`	`string`	No	ID of an `<img>` element to auto-swap with the try-on result

Theming

The widget ships with dark and light themes and supports deep customization to match your store's brand.

Theme Modes

VirtualTryOn.init({
  apiBaseUrl: 'https://api.yourdomain.com',
  tenantApiKey: 'your_key',
  theme: {
    mode: 'light',  // 'dark' (default) or 'light'
  },
});

Custom Brand Colors

Override individual properties to match your brand:

VirtualTryOn.init({
  apiBaseUrl: 'https://api.yourdomain.com',
  tenantApiKey: 'your_key',
  theme: {
    mode: 'dark',
    accentColor: '#7C3AED',          // Primary button & accent color
    accentTextColor: '#FFFFFF',       // Text color on accent buttons
    borderRadius: '8px',             // Border radius for cards & modals
    fontFamily: '"Inter", sans-serif',
    headingFontFamily: '"Playfair Display", serif',
    buttonOutlineColor: '#7C3AED',   // Outline on the split button
  },
});

Available Theme Options

Property	Type	Default	Description
`mode`	`'dark' \| 'light'`	`'dark'`	Base color palette
`accentColor`	CSS color	`#adcfab` (dark) / `#4d7c4b` (light)	Primary action color
`accentTextColor`	CSS color	`#193620` (dark) / `#ffffff` (light)	Text on accent buttons
`borderRadius`	CSS value	`12px`	Corner rounding for cards and modals
`fontFamily`	CSS font stack	`'Manrope', system-ui, sans-serif`	Body text font
`headingFontFamily`	CSS font stack	`'Newsreader', serif`	Heading font
`buttonOutlineColor`	CSS color	`transparent`	Border color on the try-on button

All UI is rendered inside a Shadow DOM, so your site's CSS will never leak into the widget and the widget will never break your styles.

Full Example

<!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="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({
      apiBaseUrl: 'https://api.yourdomain.com',
      tenantApiKey: 'pk_live_abc123',
      theme: { mode: 'light', accentColor: '#2563EB' },
      onGenerationSuccess: (url) => {
        console.log('Try-on result:', url);
      },
      onError: (msg) => {
        console.error('Try-on error:', msg);
      },
    });

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

Keys & Authentication

Key	Where to use	Purpose
Publishable API Key (`tenantApiKey`)	In your frontend code	Identifies your store — safe to expose in client-side code
Secret API Key	Backend only, never in frontend	Used for server-to-server API calls (manage your account, view usage, etc.)

Your API keys are available in your Souldi Dashboard. The publishable key is scoped to the domains you whitelist — it cannot be used from unauthorized origins.

Security note: The widget communicates exclusively with your Souldi API endpoint. No third-party services are contacted from the browser. All authentication, file uploads, and AI generation are handled server-side.

Browser Support

Works in all modern browsers:

Chrome 80+
Firefox 78+
Safari 14+
Edge 80+

License

UNLICENSED - Proprietary software. See your Souldi service agreement for usage terms.