# TryYourSize React SDK reference

---

# React reference (@tryyoursize/react)

> A provider, hooks and element components for TryYourSize.js, shaped like @stripe/react-stripe-js.

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

*SDK* · `@tryyoursize/react` · v0.1.0

React components for [TryYourSize.js](https://docs.tryyoursize.com/reference/web.md): wrap your app (or product page) in `TryYourSizeProvider`, then render `SizeGuide`, `FitButton` or `FitElement` where shoppers choose a size. Components mount on commit and are destroyed on unmount (StrictMode safe); changing `product` updates the element in place; changing a callback never reloads anything. Nothing touches `window` during render, so server-side rendering works.

## Install

**npm**

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

## Quick example

**React**

```tsx

const tysPromise = loadTryYourSize("pk_test_…");

  const [size, setSize] = useState<string>();
  return (
    <TryYourSizeProvider client={tysPromise}>
      <SizeGuide product={sku} onRecommendation={(r) => r.status === "ready" && setSize(r.size ?? undefined)} />
    </TryYourSizeProvider>
  );
}
```

## Provider and hooks

| | |
|---|---|
| [`TryYourSizeProvider`](https://docs.tryyoursize.com/reference/react/tryyoursize-provider.md) | Creates (or adopts) the TryYourSize client and its elements group for the components inside it. |
| [`useTryYourSize()`](https://docs.tryyoursize.com/reference/react/use-tryyoursize.md) | The TryYourSize client, or null until it has loaded. |
| [`useElements()`](https://docs.tryyoursize.com/reference/react/use-elements.md) | The provider's Elements group, or null until the client has loaded. |

## Components

| | |
|---|---|
| [`SizeGuide`](https://docs.tryyoursize.com/reference/react/size-guide.md) | A link-sized "Size guide" with the TryYourSize mark, for the spot next to your size picker. |
| [`FitButton`](https://docs.tryyoursize.com/reference/react/fit-button.md) | A compact "Find my size" button that opens the measuring window. |
| [`FitElement`](https://docs.tryyoursize.com/reference/react/fit-element.md) | The inline element (sign-in and "your body is ready" in your page). |
| [`ElementHandle`](https://docs.tryyoursize.com/reference/react/element-handle.md) | What a ref on <SizeGuide>, <FitButton> or <FitElement> gives you. |

---

# ElementHandle

> What a ref on <SizeGuide>, <FitButton> or <FitElement> gives you.

Source: https://docs.tryyoursize.com/reference/react/element-handle/

*Type* · `@tryyoursize/react`

What a `ref` on `<SizeGuide>`, `<FitButton>` or `<FitElement>` gives you.

```ts
interface ElementHandle
```

## Methods

- **`open`** (`void`, required): Opens the measuring window.
- **`close`** (`void`, required)
- **`getElement`** (`TysElement | null`, required): The underlying SDK element (null before mount).
- **`getRecommendation`** (`Promise<Recommendation>`, required): The shopper's recommended size once known.

## Example

**React**

```tsx
const guide = useRef<ElementHandle>(null);

<SizeGuide ref={guide} product="SKU-123" />
<button onClick={() => guide.current?.open()}>Size help</button>
```

---

# <FitButton>

> A compact "Find my size" button that opens the measuring window.

Source: https://docs.tryyoursize.com/reference/react/fit-button/

*Component* · `@tryyoursize/react`

A compact "Find my size" button that opens the measuring window.

Pass a `ref` to get an [`ElementHandle`](https://docs.tryyoursize.com/reference/react/element-handle.md) (`open()`, `close()`, `getRecommendation()`, `getElement()`).

```ts
FitButton: ForwardRefExoticComponent<ElementProps & RefAttributes<ElementHandle>>
```

## Props

- **`product`** (`string`, required): Your product identifier, as synced to TryYourSize. Changing it updates the element in place.
- **`id`** (`string`, optional)
- **`className`** (`string`, optional)
- **`style`** (`CSSProperties`, optional)
- **`onReady`** (`(e: ElementEvents["ready"]) => void`, optional): The element is shown and connected.
- **`onSize`** (`(e: SizeEvent) => void`, optional): The shopper got a size for this product: preselect the variant.
- **`onOpen`** (`(e: ElementEvents["open"]) => void`, optional)
- **`onClose`** (`(e: ElementEvents["close"]) => void`, optional)
- **`onLoadError`** (`(e: ElementEvents["loaderror"]) => void`, optional): Our window could not be reached (network, CSP).
- **`onRecommendation`** (`(r: Recommendation) => void`, optional): The shopper's recommended size in your size labels: on mount when they are already connected, and on every change. Sizes only. Preselect your picker.

## Example

**React**

```tsx
<FitButton product="SKU-123" onSize={({ size }) => setSize(size)} />
```

**JavaScript**

```js
elements.create("button", { product: "SKU-123" }).mount("#find-my-size");
```

---

# <FitElement>

> The inline element (sign-in and "your body is ready" in your page).

Source: https://docs.tryyoursize.com/reference/react/fit-element/

*Component* · `@tryyoursize/react`

The inline element (sign-in and "your body is ready" in your page). Recommended.

Pass a `ref` to get an [`ElementHandle`](https://docs.tryyoursize.com/reference/react/element-handle.md) (`open()`, `close()`, `getRecommendation()`, `getElement()`).

```ts
FitElement: ForwardRefExoticComponent<ElementProps & RefAttributes<ElementHandle>>
```

## Props

- **`product`** (`string`, required): Your product identifier, as synced to TryYourSize. Changing it updates the element in place.
- **`id`** (`string`, optional)
- **`className`** (`string`, optional)
- **`style`** (`CSSProperties`, optional)
- **`onReady`** (`(e: ElementEvents["ready"]) => void`, optional): The element is shown and connected.
- **`onSize`** (`(e: SizeEvent) => void`, optional): The shopper got a size for this product: preselect the variant.
- **`onOpen`** (`(e: ElementEvents["open"]) => void`, optional)
- **`onClose`** (`(e: ElementEvents["close"]) => void`, optional)
- **`onLoadError`** (`(e: ElementEvents["loaderror"]) => void`, optional): Our window could not be reached (network, CSP).
- **`onRecommendation`** (`(r: Recommendation) => void`, optional): The shopper's recommended size in your size labels: on mount when they are already connected, and on every change. Sizes only. Preselect your picker.
- **`demo`** (`DemoOptions`, optional): <FitElement> only, test keys only: demo mode on a named sample body, no sign-in (landing pages). Changing `demo.body` switches the body in place.
  - **`body`** (`string`, required): A sample body id, e.g. `sample-female-165`.
  - **`height`** (`number`, optional): Height of the element in px (default 640).

## Example

**React**

```tsx
<FitElement product="STRAIGHT-JEANS" onSize={({ size }) => selectVariant(size)} />
```

**JavaScript**

```js
elements.create("fit", { product: "STRAIGHT-JEANS" }).mount("#tys-fit");
```

---

# <SizeGuide>

> A link-sized "Size guide" with the TryYourSize mark, for the spot next to your size picker.

Source: https://docs.tryyoursize.com/reference/react/size-guide/

*Component* · `@tryyoursize/react`

A link-sized "Size guide" with the TryYourSize mark, for the spot next to your size picker. Shows "Your size: M" when the shopper is connected.

Pass a `ref` to get an [`ElementHandle`](https://docs.tryyoursize.com/reference/react/element-handle.md) (`open()`, `close()`, `getRecommendation()`, `getElement()`).

```ts
SizeGuide: ForwardRefExoticComponent<SizeGuideProps & RefAttributes<ElementHandle>>
```

## Props

- **`variant`** (`"link" | "button"`, optional): A text link (default) or an outlined button.
- **`label`** (`string`, optional): Your own words for "Size guide" (otherwise localized).

## Example

**React**

```tsx
<SizeGuide
  product="SKU-123"
  variant="link"
  onRecommendation={(r) => r.status === "ready" && !touched && setSize(r.size!)}
/>
```

**JavaScript**

```js
elements.create("sizeGuide", { product: "SKU-123", variant: "link" }).mount("#size-guide");
```

**HTML**

```html
<tys-size-guide publishable-key="pk_test_…" product="SKU-123"></tys-size-guide>
```

---

# <TryYourSizeProvider>

> Creates (or adopts) the TryYourSize client and its elements group for the components inside it.

Source: https://docs.tryyoursize.com/reference/react/tryyoursize-provider/

*Component* · `@tryyoursize/react`

Creates (or adopts) the TryYourSize client and its elements group for the components inside it. Pass either `publishableKey` or `client`; it cannot change once set.

```ts
function TryYourSizeProvider(props: TryYourSizeProviderProps): ReactNode
```

## Props

- **`children`** (`ReactNode`, optional)
- **`options`** (`TryYourSizeProviderOptions`, optional)
  - **`embedOrigin`** (`string`, optional): Development override of our windows' origin (e.g. http://localhost:5173). Used with `publishableKey`.
  - **`apiOrigin`** (`string`, optional): Development override of the API origin (e.g. http://localhost:8000): the A/B holdout config.
  - **`locale`** (`Locale`, optional): Language of our windows; "auto" follows the browser.
  - **`appearance`** (`Appearance`, optional): Look and feel. Changes are applied live with `elements.update()`.
- **`publishableKey`** (`string`, optional): Either this or `client`. Your publishable key (`pk_test_…` / `pk_live_…`). The provider calls `TryYourSize()`.
- **`client`** (`TryYourSizeClient | Promise<TryYourSizeClient | null> | null`, optional): Either this or `publishableKey`. A client, a promise of one (for example `loadTryYourSize(pk)`), or `null` while you don't have one yet.

## Example

**React**

```tsx
// With a key
<TryYourSizeProvider publishableKey="pk_test_…" options={{ locale: "es" }}>
  <App />
</TryYourSizeProvider>

// With the CDN loader (SSR-safe)
const tysPromise = loadTryYourSize("pk_test_…");
<TryYourSizeProvider client={tysPromise}>
  <App />
</TryYourSizeProvider>
```

**JavaScript**

```js
// Without React
const tys = TryYourSize("pk_test_…", { locale: "es" });
const elements = tys.elements();
```

---

# useElements()

> The provider's Elements group, or null until the client has loaded.

Source: https://docs.tryyoursize.com/reference/react/use-elements/

*Hook* · `@tryyoursize/react`

The provider's Elements group, or null until the client has loaded.

```ts
function useElements(): Elements | null
```

## Returns

`Elements | null`: The provider's elements group, or `null` until the client has loaded. Throws outside a provider.

## Example

**React**

```tsx
const elements = useElements();
const openGuide = () => elements?.getElement("sizeGuide")?.open();
```

---

# useTryYourSize()

> The TryYourSize client, or null until it has loaded.

Source: https://docs.tryyoursize.com/reference/react/use-tryyoursize/

*Hook* · `@tryyoursize/react`

The TryYourSize client, or null until it has loaded.

```ts
function useTryYourSize(): TryYourSizeClient | null
```

## Returns

`TryYourSizeClient | null`: The client, or `null` until it has loaded. Throws outside a provider.

## Example

**React**

```tsx
function SizeBadge({ sku }: { sku: string }) {
  const tys = useTryYourSize();
  const [size, setSize] = useState<string | null>(null);
  useEffect(() => {
    tys?.recommendation(sku).then((r) => setSize(r.status === "ready" ? r.size : null));
  }, [tys, sku]);
  return size ? <span>Your size: {size}</span> : null;
}
```