# Web SDK reference (TryYourSize.js)

> TryYourSize.js for any storefront: the client, elements, events and web components.

Source: https://docs.tryyoursize.com/reference/web/

*SDK* · `@tryyoursize/sdk` · v0.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 tag**

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

**npm**

```bash
npm install @tryyoursize/sdk
```

## Initialize

**JavaScript**

```js

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"
});
```

**React**

```tsx

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

**HTML**

```html
<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](https://docs.tryyoursize.com/sdk/errors.md).

## Client

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

## Elements group

| | |
|---|---|
| [`create()`](https://docs.tryyoursize.com/reference/web/elements-create.md) | Creates an element for one product. |
| [`getElement()`](https://docs.tryyoursize.com/reference/web/elements-get-element.md) | The most recently created element of a type that is still alive, or null. |
| [`update()`](https://docs.tryyoursize.com/reference/web/elements-update.md) | Live update, e.g. |

## Element

| | |
|---|---|
| [`mount()`](https://docs.tryyoursize.com/reference/web/element-mount.md) | Shows the element inside a container of your page. |
| [`unmount()`](https://docs.tryyoursize.com/reference/web/element-unmount.md) | Removes the element from the page and closes its window. |
| [`destroy()`](https://docs.tryyoursize.com/reference/web/element-destroy.md) | Unmounts the element and drops its handlers. |
| [`update()`](https://docs.tryyoursize.com/reference/web/element-update.md) | Changes the element's options in place. |
| [`open()`](https://docs.tryyoursize.com/reference/web/element-open.md) | Opens the TryYourSize window for this element's product, as the element itself does on click. |
| [`close()`](https://docs.tryyoursize.com/reference/web/element-close.md) | Closes the window if it is open. |
| [`getRecommendation()`](https://docs.tryyoursize.com/reference/web/element-get-recommendation.md) | The shopper's recommended size for this product once known (see the recommendation event). |
| [`on()`](https://docs.tryyoursize.com/reference/web/element-on.md) | Listens to an element event. |
| [`once()`](https://docs.tryyoursize.com/reference/web/element-once.md) | Like on(), for the next event only. |
| [`off()`](https://docs.tryyoursize.com/reference/web/element-off.md) | Removes a handler, or every handler of the event when you pass none. |
| [`elementType`](https://docs.tryyoursize.com/reference/web/element-element-type.md) | 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"`](https://docs.tryyoursize.com/reference/web/event-ready.md) | The element is on the page (the size guide and button at once; the inline element once our window is connected). |
| [`"size"`](https://docs.tryyoursize.com/reference/web/event-size.md) | The shopper chose a size in our window ("Use this size"): preselect that variant. |
| [`"open"`](https://docs.tryyoursize.com/reference/web/event-open.md) | Our window opened. |
| [`"close"`](https://docs.tryyoursize.com/reference/web/event-close.md) | Our window closed. |
| [`"loaderror"`](https://docs.tryyoursize.com/reference/web/event-loaderror.md) | Our window could not be loaded or reached (network, Content Security Policy, an origin not registered for the key). |
| [`"recommendation"`](https://docs.tryyoursize.com/reference/web/event-recommendation.md) | 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>`](https://docs.tryyoursize.com/reference/web/tys-size-guide.md) | The size guide element as a tag: "Size guide" with the TryYourSize mark, then "Your size: M" once the shopper is connected. |
| [`<tys-fit>`](https://docs.tryyoursize.com/reference/web/tys-fit.md) | The inline element as a tag: sign-in and "your body is ready" in your page. |
| [`<tys-fit-button>`](https://docs.tryyoursize.com/reference/web/tys-fit-button.md) | The compact "Find my size" button as a tag. |

## Types and utilities

| | |
|---|---|
| [`Appearance`](https://docs.tryyoursize.com/reference/web/appearance.md) | Look and feel of the elements and our windows, modelled on Stripe's Appearance API: a theme, a few variables, and web fonts. |
| [`Recommendation`](https://docs.tryyoursize.com/reference/web/recommendation.md) | Recommendation |
| [`TryYourSizeError`](https://docs.tryyoursize.com/reference/web/tryyoursize-error.md) | Every error the SDK throws or emits: a stable type and code to branch on, a message, and a link to its explanation. |
| [`isPublishableKey()`](https://docs.tryyoursize.com/reference/web/is-publishable-key.md) | A publishable key is the only key allowed in a browser. |
| [`resolveAppearance()`](https://docs.tryyoursize.com/reference/web/resolve-appearance.md) | 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`](https://docs.tryyoursize.com/reference/web/version.md) | The SDK version (semver), also sent to our windows. |