Loader configuration

Initialize virtual.fit before loading the hosted script. The queue preserves commands until the loader is ready.

Complete example

<script>
  window.virtualfit = window.virtualfit || function () {
    (window.virtualfit.q = window.virtualfit.q || []).push(arguments);
  };

  virtualfit('init', {
    siteKey: 'site_pub_your_key',
    mount: '.product-media',
    overlayPosition: 'bottom-right',
    auth: {
      showToAnonymous: true,
      loginUrl: ({ returnTo }) =>
        '/account/login?return_to=' + encodeURIComponent(returnTo)
    },
    customer: window.currentCustomer
      ? {
          id: window.currentCustomer.id,
          email: window.currentCustomer.email
        }
      : {},
    labels: {
      triggerButton: 'Try it on',
      generateButton: 'Generate try-on'
    },
    terms: {
      fullSelector: '#virtual-fit-terms'
    }
  });
</script>
<script async src="https://virtual.fit/vfr/v1/vfr.js"></script>

Initialization fields

Field	Type	Default	Description
`siteKey`	`string`	Required	Public key shown in virtual.fit.
`mount`	CSS selector or `Element`	Automatic	Main product media host. Set this explicitly when automatic placement does not select the full gallery.
`overlayPosition`	`string`	`top-right`	`top-right`, `top-left`, `bottom-right`, or `bottom-left`.
`product`	`object`	URL-resolved	Optional explicit product context.
`customer`	`object`	Anonymous	Current customer `id` and optional `email`.
`auth`	`object`	Anonymous visible	Login visibility and destination.
`labels`	`object`	English defaults	Shopper-facing labels and messages.
`terms`	`object`	Default terms	Summary, full terms, and email controls.
`language`	`string`	`en`	Language identifier for terms configuration.
`overlayTargetSelector`	`string`	Automatic	Advanced gallery host override.
`overlayImageSelector`	`string`	`img`	Image inside the overlay target.
`gallerySelector`	`string`	Empty	Advanced result-gallery selector.
`thumbnailSelector`	`string`	Empty	Advanced thumbnail selector.

Start with siteKey, mount, and terms. Add advanced selectors only after the basic integration works.

Product object

{
  id: 'dress-10042',
  handle: 'linen-midi-dress',
  title: 'Linen Midi Dress',
  imageUrl: 'https://cdn.example.com/linen-midi-dress.jpg',
  variantId: 'linen-black-petite-2',
  variantImageUrl: 'https://cdn.example.com/linen-black.jpg'
}

Provide id or handle. The loader verifies it against the synced enabled catalog before mounting.

string

Stable product ID from catalog sync. Keep this ID unchanged when the shopper selects another variant.

string

Synced product handle. Provide id or handle.

string

Current shopper-facing title.

string

Product display fallback. It does not replace canonical prepared media.

string

Optional exact source_variant_id synced under the product.

string

Optional selected-variant display hint. Canonical synced variant media remains authoritative for try-on.

Call setProduct when a dynamic storefront changes the product or selected variant. See the Browser API.

Customer and authentication

auth: {
  showToAnonymous: true,
  loginUrl: ({ returnTo, product, location }) =>
    '/login?return_to=' + encodeURIComponent(returnTo)
},
customer: {
  id: 'customer-8421',
  email: '[email protected]'
}

auth.loginUrl accepts a string or callback. The callback receives:

returnTo — Current absolute page URL.
product — Resolved product context, or null.
location — Current href, origin, pathname, search, and hash.

showToAnonymous controls whether a logged-out shopper can see a login call to action when your virtual.fit settings require authentication. The customer-access policy in virtual.fit remains authoritative.

Terms object

terms: {
  summaryHtml: 'AI preview only. Actual fit may differ.',
  fullSelector: '#virtual-fit-terms',
  collectEmail: false,
  requireEmail: false,
  emailNote: 'We will send this try-on result to the address you provide.'
}

Use one source for full terms:

fullHtml — Pass full HTML directly.
fullSelector — Read innerHTML from an existing host-page element.

If neither is set, virtual.fit uses its default terms. See Styling, labels, and terms.

Single-tag installation

When a platform allows one script tag but no inline queue, use data attributes:

<script
  async
  src="https://virtual.fit/vfr/v1/vfr.js"
  data-site-key="site_pub_your_key"
  data-mount=".product-media"
  data-overlay-position="bottom-right"
  data-labels='{"triggerButton":"Try it on","generateButton":"Generate try-on"}'
  data-show-to-anonymous="true"
  data-login-url="/account/login"
  data-product-id="sku-10042"
  data-product-handle="linen-midi-dress"
  data-product-title="Linen Midi Dress"
  data-product-image="https://cdn.example.com/linen-midi-dress.jpg"
  data-product-variant-id="linen-black-petite-2"
  data-product-variant-image="https://cdn.example.com/linen-black.jpg"
  data-customer-id="customer-8421"
></script>

JavaScript initialization is preferred when values are dynamic, variant selection changes after page load, or loginUrl needs callback logic.

Legacy aliases

Use terms for disclaimer and legal content. Use labels for interface text. Older content and ui aliases remain accepted for existing installs, but new integrations should not depend on them.

Get started

Shopify

Custom JavaScript

Recommendations

Operate

API reference

Complete example

Initialization fields

Product object

Customer and authentication

Terms object

Single-tag installation

Legacy aliases

​Complete example

​Initialization fields

​Product object

​Customer and authentication

​Terms object

​Single-tag installation

​Legacy aliases

Complete example

Initialization fields

Product object

Customer and authentication

Terms object

Single-tag installation

Legacy aliases