xactsize-webcomponent

A lightweight Web Component for precise body measurements and size recommendations in web applications, built with Lit.

Installation

npm install xactsize-webcomponent

<body-measurer
  culture="pt-BR"
  product-name="Shirt"
  skus='[{"dimensions":{"Size":"M"},"measures":{"height":50,"length":70,"width":40}}]'
></body-measurer>
<script>
  import { BodyMeasurer } from "xactsize-webcomponent";

  // Select the body-measurer element
  const bodyMeasurer = document.querySelector("body-measurer");

  // Check if the element exists
  if (bodyMeasurer) {
    // Add event listener for measurementAccepted
    bodyMeasurer.addEventListener("measurementAccepted", (e) => {
      const size = e.detail.size;
      alert(`Size selected: ${size}`);
      console.log("Measurement accepted:", e.detail);
    });

    // Add event listener for measurementCanceled
    bodyMeasurer.addEventListener("measurementCanceled", (e) => {
      alert("Measurement canceled");
      console.log("Measurement canceled");
    });
  } else {
    console.error("body-measurer element not found");
  }
</script>

<body-measurer
  culture="pt-BR"
  product-name="Calça Legging"
  skus='[{"dimensions":{"Size":"S"},"measures":{"height":39,"length":78,"width":78}},{"dimensions":{"Size":"M"},"measures":{"height":40,"length":82,"width":82}}]'
></body-measurer>
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/[email protected]/dist/body-measurer.es.js"
></script>

<script>
  // Select the body-measurer element
  const bodyMeasurer = document.querySelector("body-measurer");

  // Check if the element exists
  if (bodyMeasurer) {
    // Add event listener for measurementAccepted
    bodyMeasurer.addEventListener("measurementAccepted", (e) => {
      const size = e.detail.size;
      alert(`Size selected: ${size}`);
      console.log("Measurement accepted:", e.detail);
    });

    // Add event listener for measurementCanceled
    bodyMeasurer.addEventListener("measurementCanceled", (e) => {
      alert("Measurement canceled");
      console.log("Measurement canceled");
    });
  } else {
    console.error("body-measurer element not found");
  }
</script>
</script>

Virtual Try-On (VTON)

The component supports generating a Virtual Try-On image of the user wearing a specific garment. The generated image will be shown on the final results step alongside the size recommendation.

To enable this feature, provide the following properties to the <body-measurer> element:

• vton (boolean): Set this attribute to enable the Virtual Try-On flow.
• garment-url (string): The URL of the garment image you want the user to try on.
• vton-url (string, optional): The API endpoint for generating the VTON image. Defaults to https://xactsize-dotnet-api-923169850574.southamerica-east1.run.app/api/VirtualTryOn/generate.

Example

<body-measurer
  culture="pt-BR"
  product-name="Shirt"
  vton
  garment-url="https://example.com/images/shirt.jpg"
  skus='[{"dimensions":{"Size":"M"},"measures":{"height":50,"length":70,"width":40}}]'
></body-measurer>

Usage and Implementation Guide

The <body-measurer> component is highly customizable and accepts various attributes to control its behavior, appearance, and integration with the Xactsize backend.

Properties (Attributes)

Here is a list of all supported attributes that can be passed to the <body-measurer> element:

| Attribute | Type | Default | Description | | ------------- | ------- | ----------- | ------------------------------------------------------------------------------- | | api-key | string | "" | Your Xactsize API key for backend authentication. | | tenant-id | string | "1" | Your tenant identifier. | | product-sku | string | "123456" | The unique SKU of the product being sized. This is required for API resolution. | | base-url | string | default | The base URL for the Xactsize service API. | | api-url | string | default | The endpoint for the main sizing API. | | vton | boolean | false | Enables the Virtual Try-On (VTON) feature. | | vton-url | string | default | The API endpoint for generating VTON images. | | garment-url | string | "" | The URL of the garment image used for Virtual Try-On. | | brand-name | string | undefined | Displays your brand's name in the component (e.g., "Xactsize x YourBrand"). | | button-text | string | "" | Custom text for the "Find My Size" launch button. | | culture | string | "en" | The active locale for the UI. Supported options: "en", "pt-BR", "es-MX". |

Note: While older integration examples might show skus or product-name attributes, modern implementations rely on the product-sku attribute which the backend uses to resolve product sizing rules.

Events

The component emits standard DOM custom events that you can listen to in your application logic:

• measurementAccepted: Fired when the user accepts the recommended size.
  • event.detail contains the sizing result payload (e.g., { size: "M" }).
• measurementCanceled: Fired when the user closes the modal or explicitly aborts the process.

Localization (i18n)

The component fully supports internationalization. To change the language, simply update the culture attribute on the element. Available cultures:

• en (English)
• pt-BR (Portuguese - Brazil)
• es-MX (Spanish - Mexico)

The localization engine will automatically apply the translated strings to all steps in the flow.

Example Implementation

<body-measurer
  api-key="YOUR_API_KEY_HERE"
  tenant-id="123"
  product-sku="SHIRT-001"
  brand-name="My Store"
  culture="es-MX"
  button-text="Encontrar mi talla"
  vton
  garment-url="https://example.com/shirt-image.jpg"
>
</body-measurer>

<script>
  const measurer = document.querySelector("body-measurer");

  measurer.addEventListener("measurementAccepted", (e) => {
    console.log("User accepted size:", e.detail.size);
    // Logic to add the selected size to the shopping cart
  });

  measurer.addEventListener("measurementCanceled", () => {
    console.log("User closed the measurer");
  });
</script>