Configuration Reference

Every option accepted by new THGVTO(options) and vto.getProduct(options), plus the TypeScript interfaces used by them.

THGVTOOptions

Passed to new THGVTO(options).

interface THGVTOOptions {
  /** API base URL. Falls back to script[data-api-url]. */
  apiUrl?: string;
  /** API key. Falls back to script[data-api-key]. */
  apiKey?: string;

  /** Theme overrides. */
  theme?: VtoTheme;
  /** Content/label overrides. */
  content?: VtoContent;
  /** Watermark for downloaded/shared images. */
  watermark?: VtoWatermark;
  /** GDPR consent. Both default to true. */
  consent?: { photoProcessing?: boolean; photoStorage?: boolean };

  /** Remove/replace background on person photo upload. Default: false. */
  processBackground?: boolean;

  /** Enable generation history in modal. Default: true. */
  historyEnabled?: boolean;
  /** Max history entries. Default: 10. */
  historyMax?: number;

  /** Show onboarding to first-time users. Default: true. */
  showOnboarding?: boolean;
  /** Show "Add to Bag" on result. Default: false. */
  showAddToCart?: boolean;
  /** Show wishlist action on result. Default: false. */
  showWishlist?: boolean;

  /** Allow predefined model selection. Default: false. */
  modelsEnabled?: boolean;
  /** Show QR code for mobile upload on desktop. Default: false. */
  qrEnabled?: boolean;
}

ProductOptions

Passed to vto.getProduct(options).

interface ProductOptions {
  /** Product page URL — also used for analytics. (required) */
  url: string;
  /** Product image URL — used for generation. (required) */
  image: string;
  /** Product title — shown in modal context bar. */
  title?: string;
  /** Product SKU/ID. */
  id?: string;
  /** Product price — shown in modal context bar. */
  price?: string;
}

VtoTheme

interface VtoTheme {
  primaryColor?: string;       // Default: '#000'
  primaryTextColor?: string;   // Default: '#fff'
  buttonRadius?: string;       // Default: '4px'
  fontFamily?: string;         // Default: 'inherit'
  modalMaxWidth?: string;      // Default: '480px'
}

Theme values are applied as CSS custom properties on the modal element. See Theming for the full list of tokens.

VtoContent

interface VtoContent {
  modalTitle?: string;       // Default: 'Virtual Try-On'
  uploadText?: string;       // Default: 'Upload a photo of yourself'
  uploadHint?: string;       // Default: 'Full body photo works best...'
  generateLabel?: string;    // Default: 'Generate Try-On'
  disclaimerText?: string;   // Default: none
}

VtoWatermark

interface VtoWatermark {
  enabled: boolean;
  text?: string;             // Text watermark (e.g. brand name)
  imageUrl?: string;         // Image watermark URL
  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center' | 'center-overlay';
  opacity?: number;          // 0-1, default: 0.3
}

VtoConsent

interface VtoConsent {
  photoProcessing: boolean;  // Required for generate() to run
  photoStorage?: boolean;    // Controls localStorage persistence of person photo
}

Caution

When photoProcessing is false, product.generate() returns null and logs a warning. Gate your trigger UI accordingly — see the consent guide.

generate() options

interface GenerateOptions {
  /**
   * 'interactive' (default) shows the modal.
   * 'direct' generates without a modal if a person photo already exists;
   *  falls back to 'interactive' when no photo is stored or direct fails.
   */
  mode?: 'interactive' | 'direct';
}

Static DOM helpers

class THGVTO {
  static clone(template: Element, imageUrl: string, badgeLabel?: string, productImage?: string): HTMLElement;
  static update(imageUrl: string, productImage?: string): boolean;
  static clear(productImage?: string): void;
  static watch(el: Element, callback: () => void, debounceMs?: number): () => void;
}

See the SDK API guide for usage patterns.