Web SDK reference (TryYourSize.js)

SDK@tryyoursize/sdkv0.2.0

TryYourSize.js puts the TryYourSize elements in your storefront: a Size guide link next to your size picker, a Find my size button, or the inline fit element. Shoppers measure once with a tape measure; your page receives their size in your own size labels, never their measurements. Same shape as Stripe.js: a client per publishable key, an elements group, elements you mount, events you listen to.

Install

Script tagnpm

<script src="https://js.tryyoursize.com/v1/tys.js"></script>
<!-- window.TryYourSize, plus <tys-fit>, <tys-fit-button> and <tys-size-guide> -->

npm install @tryyoursize/sdk

Initialize

JavaScriptReactHTML

import { TryYourSize } from "@tryyoursize/sdk";

const tys = TryYourSize("pk_test_…");            // publishable key only
const elements = tys.elements();                // inherits your page's font and colours
const guide = elements.create("sizeGuide", { product: "SKU-123" });
guide.mount("#size-guide");
guide.on("recommendation", (r) => {
  if (r.status === "ready") preselect(r.size);  // your size label, e.g. "M"
});

import { TryYourSizeProvider, SizeGuide } from "@tryyoursize/react";

export function SizePicker() {
  return (
    <TryYourSizeProvider publishableKey="pk_test_…">
      <SizeGuide product="SKU-123" onRecommendation={(r) => r.status === "ready" && preselect(r.size)} />
    </TryYourSizeProvider>
  );
}

<script src="https://js.tryyoursize.com/v1/tys.js"></script>
<tys-size-guide publishable-key="pk_test_…" product="SKU-123"></tys-size-guide>
<script>
  document.querySelector("tys-size-guide").addEventListener("tys:recommendation", (e) => {
    if (e.detail.status === "ready") preselect(e.detail.size);
  });
</script>

Allow our origins in your Content Security Policy: script-src https://js.tryyoursize.com (CDN build) and frame-src https://embed.tryyoursize.com. Error codes are listed in Web SDK errors.

Client

TryYourSize()	Creates a client for your publishable key.
loadTryYourSize()	Loads TryYourSize.js from our CDN once (the latest compatible v1 build) and creates a client, like loadStripe().
elements()	Creates an elements group: the appearance and language shared by the elements you create from it.
recommendation()	The shopper’s recommended size for a product, in your size labels, without mounting anything (a hidden frame on our origin answers).
recommendationHandle()	A sealed handle for your server’s POST /v1/recommendations (headless or server-rendered pages).
experiment()	The visitor’s A/B holdout assignment when the store runs one (null otherwise).
version	The SDK version (semver) of the loaded TryYourSize.js.

Elements group

create()	Creates an element for one product.
getElement()	The most recently created element of a type that is still alive, or null.
update()	Live update, e.g.

Element

mount()	Shows the element inside a container of your page.
unmount()	Removes the element from the page and closes its window.
destroy()	Unmounts the element and drops its handlers.
update()	Changes the element’s options in place.
open()	Opens the TryYourSize window for this element’s product, as the element itself does on click.
close()	Closes the window if it is open.
getRecommendation()	The shopper’s recommended size for this product once known (see the recommendation event).
on()	Listens to an element event.
once()	Like on(), for the next event only.
off()	Removes a handler, or every handler of the event when you pass none.
elementType	The element’s type: “fit”, “button” or “sizeGuide”.

Events

Listen with element.on(name, handler), with the React on… props, or as tys:<name> DOM events on the web components.

"ready"	The element is on the page (the size guide and button at once; the inline element once our window is connected).
"size"	The shopper chose a size in our window (“Use this size”): preselect that variant.
"open"	Our window opened.
"close"	Our window closed.
"loaderror"	Our window could not be loaded or reached (network, Content Security Policy, an origin not registered for the key).
"recommendation"	The shopper’s recommended size for this product, in your size labels: on mount when the shopper is already connected, and on every change.

Web components

For no-code platforms and CMS blocks: load tys.js (or import @tryyoursize/sdk/elements) and use the tags. Each forwards the element events as bubbling tys:<event> DOM events with the payload in event.detail.

<tys-size-guide>	The size guide element as a tag: “Size guide” with the TryYourSize mark, then “Your size: M” once the shopper is connected.
<tys-fit>	The inline element as a tag: sign-in and “your body is ready” in your page.
<tys-fit-button>	The compact “Find my size” button as a tag.

Types and utilities

Appearance	Look and feel of the elements and our windows, modelled on Stripe’s Appearance API: a theme, a few variables, and web fonts.
Recommendation	Recommendation
TryYourSizeError	Every error the SDK throws or emits: a stable type and code to branch on, a message, and a link to its explanation.
isPublishableKey()	A publishable key is the only key allowed in a browser.
resolveAppearance()	Resolves what the windows receive: for “inherit”, the font, text colour and background where the element is mounted (buttons use the text colour, the way most stores style their primary button); expli
VERSION	The SDK version (semver), also sent to our windows.