@souldi/try-on
v0.1.11
Published
Embeddable virtual try-on widget for e-commerce
Maintainers
souldi-adminReadme
@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-onOr 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.