Relay Widget SDK Reference

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

Installation

Available on npm: @persona/relay

npm

yarn

$ npm install @persona/relay

Constructors

`new Relay(container, options)`

1 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
`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 user’s OS color scheme preference

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.

1 // React example
2 useEffect(() => {
3   const client = new Relay('#relay-container', { ... });
4   return () => client.destroy();
5 }, []);

1	// React example
2	useEffect(() => {
3	const client = new Relay('#relay-container', { ... });
4	return () => client.destroy();
5	}, []);