Migrate Product Sizing

Overview of Differences (V2 → V3)

Attributes

V2 Attribute	V3 Attribute	Required in V3	Description
data-oz-widget	-	-	Determined by the custom element used
data-oz-embed	-	-	V3 automatically detects custom button implementations
data-oz-code	global-id	true	Official GTIN/SKU from manufacturer
-	variant-id	Required if product feed is active	Shop SKU / Article number
data-oz-name	name	true	Product display name
data-oz-image	image	true	URL to product preview image
data-oz-price	price	true	Sale price of the product
data-oz-fullscreen	-	-	Not currently supported (work in progress)
data-oz-labels	-	-	Will not be added in V3
data-oz-launcher-label-show	-	-	Will not be added in V3
data-oz-launcher-label-hide	-	-	Will not be added in V3
data-oz-confirm-size-label	-	-	Will not be added in V3
data-oz-confirm-size-unavailable-label	-	-	Will not be added in V3
data-oz-confirm-size-does-not-fit-label	-	-	Will not be added in V3
-	product-type	false	Force a specific product type (e.g., BIKE)
-	autosizing	false	Enables smart button (default: true)
-	workflow	false	Override API settings
-	lang	false	Override API settings (default: user preference)
-	units	false	Override API settings (e.g., imperial)
-	unit-selector-visible	false	Override API settings. Enable/disable a unit selector for the user while using the widget (default: false)
-	onselect	false	Name of the select event listener (addEventListener is preferred over this)

Callbacks

Callback	V2 Name	V3 Name	Description
Size Selected	confirmSize	select (DOM CustomEvent) onselect (attribute)	In V3, use DOM CustomEvents and custom attributes instead of defining a function in the widget config.
Code is available in our database	sizingAvailable	-	Not available in V3.
Code is NOT available in our database	sizingUnavailable	-	Previously used to display an alternative button if the widget was unavailable. In V3, use an HTML template to provide a fallback element when the widget cannot be shown.
Override availability status	checkIsAvailable	-	Not available in V3. Availability is determined exclusively via the product data feed.
Event for each widget step	usageInsights	-	Not available in V3.

---

Migration Steps

Custom Button

V2

<button data-oz-widget="sizing" data-oz-embed="custom" ...>
  What's my size?
</button>

V3 – Without Fallback

The class attribute can be any name and serves as a selector for your CSS. It is recommended to use style="visibility: hidden" to prevent the button from flickering on page load.

<sf-product-sizing ...>
  <button type="button" style="visibility: hidden" class="custom-btn"></button>
</sf-product-sizing>

V3 – With Fallback

The fallback element is displayed when the widget cannot be shown (e.g., code not available in our database or server issues). Since the custom button is wrapped in a template element, the initial visibility style is no longer necessary.

<sf-product-sizing ...>
  <!-- Element shown if the widget cannot be loaded -->
  <a href="#">Your fallback element</a>
  <!-- The template tag must be the direct parent of the button element -->
  <template>
    <button type="button" class="custom-btn"></button>
  </template>
</sf-product-sizing>

Callbacks

In V2, all callbacks were added to the widget's configuration object. In V3, widgets use standard JavaScript event listeners (recommended) or custom event attributes.

confirmSize → select/onselect

The confirmSize callback has been renamed to select (event name) and onselect (custom attribute).

Instead of:

const OZ_CONFIG = {
  ...,
  events: {
    confirmSize: {
      callback: myVariantSelectionFunction
    },
  },
};

We recommend switching to:

const widget = document.querySelector("#onlinesizing-widget");
widget?.addEventListener("select", yourSelectFunction);

or

<sf-product-sizing onselect="yourSelectFunction" ...> </sf-product-sizing>

Event Data:

In V3, the callback receives a CustomEvent instance with the following detail type:

type SizeSelectedEventInfo = {
  code: string | null; // If the feed is enabled, this is the variant ID; otherwise, the global ID.
  stock: boolean;
};

Note: V3 exposes less information about the selected size to avoid unreliable implementations based on values like displaySize01 and displaySize02. You should use the code property to match products.

Full Example

V2

<style>
  .hidden {
    display: none;
  }
  .custom-btn {
      ...
  }
</style>

<div id="my-sizing-chart" class="hidden">...</div>
<button
  id="onlinesizing-widget"
  class="custom-btn"
  data-oz-widget="sizing"
  data-oz-embed="custom"
  data-oz-code="{{ product.ean }}"
  data-oz-name="{{ product.title }}"
  data-oz-image="{{ product.image.src }}"
  data-oz-price="{{ product.price }}"
>
  What's my size?
</button>

<script>
  const myVariantSelectionFunction = (payload) => {
    const { code } = payload;
    return (window.location = `${productUrl}?variant=${variantId[code]}`);
  };
  const showSizingChart = (payload) => {
    const { code, id } = payload;
    const myButton = document.getElementById(id);
    const mySizingChart = document.getElementById("my-sizing-chart");
    myButton.classList.add("hidden");
    mySizingChart.classList.remove("hidden");
  };
  const OZ_CONFIG = {
    ...
    events: {
      confirmSize: {
        callback: myVariantSelectionFunction,
      },
      sizingUnavailable: {
        callback: showSizingChart,
      },
    },
  };
</script>

V3

<style>
  .custom-btn {
      ...
  }
</style>

<sf-product-sizing
  id="onlinesizing-widget"
  name="{{ Product title variable }}"
  global-id="{{ GTIN variable }}"
  variant-id="{{ Variant-ID variable }}"
  image="{{ Product image url }}"
  price="{{ Product price }}"
  product-type="Either BIKE or SKI"
>
  <div id="my-sizing-chart">...</div>
  <template>
    <button type="button" class="custom-btn"></button>
  </template>
</sf-product-sizing>

<script>
  const myVariantSelectionFunction = (event) => {
    const code = event.detail.code;
    const inStock = event.detail.stock;
    if (inStock) {
      return (window.location = `${productUrl}?variant=${variantId[code]}`);
    }
  };

  const widget = document.querySelector("#onlinesizing-widget");
  widget?.addEventListener("select", myVariantSelectionFunction);
</script>