React quickstart

For your developer

What it does: Adds TryYourSize components to our React storefront: a size guide next to the size picker and the recommended size in our own labels. We receive sizes only.

Time needed: An afternoon.

What to send them: The publishable key (pk_test_…) and our site origins to register in Studio.

The components work like @stripe/react-stripe-js: one provider near the root of your app, and element components where you want them.

npm install @tryyoursize/react @tryyoursize/sdk

Quick start

import { useState } from "react";
import { loadTryYourSize } from "@tryyoursize/sdk/loader";
import { TryYourSizeProvider, FitElement } from "@tryyoursize/react";

// Once, outside render, so you don't create a new client on every render.
const tysPromise = loadTryYourSize("pk_test_…");

export function App() {
  return (
    <TryYourSizeProvider client={tysPromise} options={{ appearance: { variables: { borderRadius: 4 } } }}>
      <ProductPage />
    </TryYourSizeProvider>
  );
}

function ProductPage() {
  const [size, setSize] = useState<string | null>(null);
  return (
    <>
      <SizePicker value={size} onChange={setSize} />
      <FitElement product="SKU-123" onSize={({ size }) => setSize(size)} />
    </>
  );
}

If you bundle the SDK from npm instead of loading it from our CDN, pass the key: <TryYourSizeProvider publishableKey="pk_test_…">.

<TryYourSizeProvider>

Prop
publishableKey	Your publishable key. The provider creates the client in the browser.
client	Instead of publishableKey, a client or a promise of one (for example loadTryYourSize()). null means “not yet”: elements wait.
options.appearance	See Appearance. Changes apply live; an inline object does not cause updates on every render.
options.locale	"auto" or a language. Read once, when the client is created.

The client cannot change after it is set; if it changes, the provider logs a warning and keeps the first client.

Components

• <SizeGuide>: the link-sized size guide, next to your size picker. variant="link" or "button".
• <FitElement>: the inline element (recommended). <FitButton>: the compact “Find my size” button.

Prop
product (required)	Your product ID or SKU. Changing it calls update({ product }), not a new element.
onSize	({ product, size, verified }) => void: the shopper chose a size in our window.
onRecommendation	({ product, status, size, studioSize, wearableSizes }) => void. See Recommended size.
onReady, onOpen, onClose, onLoadError	The SDK events with the same names.
id, className, style	Applied to the mount <div>.

<SizeGuide
  product="SKU-123"
  onRecommendation={({ status, size }) => status === "ready" && !touched && setSize(size!)}
/>

A ref gives you { open(), close(), getElement() }:

const fit = useRef<ElementHandle>(null);
<button onClick={() => fit.current?.open()}>Measure me</button>
<FitElement ref={fit} product="SKU-123" />

Hooks

• useTryYourSize() returns the client, or null until it has loaded. Use it for the client methods, for example await tys.recommendationHandle() to send a sealed handle to your server (Server-side recommendations).
• useElements() returns the provider’s elements group, or null until loaded: use it for elements.update({ appearance }).

Guarantees

• Mount on commit, destroy on unmount. Under <StrictMode> only one iframe is ever live.
• SSR-safe. Importing and server rendering never touch window; on the server you get an empty mount <div>.
• Stable handlers. Changing an event handler never reloads the iframe.