> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpersona.com/2020-05-18/relay-sdk-reference/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server.

# Relay Widget SDK Reference

> Full API reference for the Persona Relay Widget SDK.

This page documents the full client-side API for the Persona Relay SDK.

## Installation

Available on npm: [`@persona/relay`](https://www.npmjs.com/package/@persona/relay)

#### npm

```bash
npm install @persona/relay
```

#### yarn

```bash
yarn add @persona/relay
```

## Constructors

### `new Relay(container, options)`

```typescript
new Relay(container: string | HTMLElement, options: RelayOptions)
```

**Arguments**

| Argument    | Type                    | Required | Description                                                                                                  |
| ----------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `container` | `string \| HTMLElement` | true     | A CSS selector string (e.g. `'#relay-container'`) or a direct DOM element reference to mount the widget into |
| `options`   | `RelayOptions`          | true     | Configuration for the relay session. See [`RelayOptions`](#relayoptions) for available fields.               |

**`RelayOptions`**

| Field         | Type                          | Required | Description                                                                                                                                  |
| ------------- | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `accessToken` | `string`                      | true     | The relay session access token returned by your server                                                                                       |
| `onComplete`  | `() => void`                  | false    | Called when relay verification completes successfully                                                                                        |
| `onError`     | `(error: RelayError) => void` | false    | Called when a configuration or network error occurs                                                                                          |
| `onExpire`    | `() => void`                  | false    | Called when the relay session expires                                                                                                        |
| `theme`       | `'light' \| 'dark' \| 'auto'` | false    | Color theme for the widget. Defaults to `'auto'`, which follows the browser's color scheme preference (usually mirrors OS / device setting). |

**`RelayError`**

| Field     | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| `code`    | `string` | Machine-readable error code               |
| `message` | `string` | Optional human-readable error description |

## Methods

### `client.destroy()`

Unmounts the widget, removes all iframes from the DOM, and cleans up all event listeners and observers. Call this when the widget is no longer needed.

```typescript
// React example
useEffect(() => {
  const client = new Relay('#relay-container', { ... });
  return () => client.destroy();
}, []);
```

> Full API reference for the Persona Relay Widget SDK.