What is the Embedded Widget?
The Embedded Widget is one of the ways a user can complete a Relay verification. It renders the verification directly inside your own web page, so the user never leaves your site.
To a user, it starts as a lightweight, familiar checkbox-style step in your existing form. Behind it, Relay runs the verification flow for the claim type you asked for.
When would you use it?
Choose the Embedded Widget when you want Relay to feel like part of your page. It suits a signup form, a checkout step, or any gate that sits inline in a flow the user is already moving through.
Choose Hosted Flow instead when you would rather hand the user off to a Persona-hosted page. Some teams prefer that because a visibly separate experience helps reinforce for users that verification is happening away from the site they are using.
For native apps, see Relay on iOS and Android.
How it fits your integration
The widget is the client-side half of a Relay integration. Your server creates the Relay session and passes the Relay session access token to the page; the widget uses that token to run the verification.
A few things worth knowing before you build:
- The widget is distributed as the
@persona/relaynpm package. You give it a container element and a set of options. - It calls back when the flow finishes. That callback carries no personal information and no claim result, so it is a signal to call your own server, not a source of the answer.
- A Relay session expires a set time after it is created, and the widget reports expiry so you can handle it. The documentation has the current window.
- You can set the theme to light, dark, or auto.
Try it
The public demo at explore.withpersona.com/relay runs the widget inside a sample signup form, with an activity panel showing each step as it happens. You can switch that panel to a technical view to see the same steps as SDK, gateway, or raw API calls.
Full technical documentation
The developer documentation is the source of truth for the integration:
Plans Explained
Embedded Widget by plan
| Startup Program | Essential Plan | Growth Plan | Enterprise Plan | |
|---|---|---|---|---|
| Embedded Widget | Available | Available | Available | Available |