@formsort/react-embed
Embed Formsort flows within react components.
This is a handy wrapper around @formsort/web-embed-api.
Important note: This package is intended for use in React web applications. If you're looking to embed Formsort flows in React Native applications, please see React native embed guide.
Installation
Add @formsort/react-embed to your project by executing pnpm add @formsort/react-embed, yarn add @formsort/react-embed, or npm install @formsort/react-embed.
Usage
Here's an example of basic usage:
import React from 'react';
import EmbedFlow from '@formsort/react-embed';
const EmbedFlowExample: React.FunctionComponent = () => (
<div>
<EmbedFlow
clientLabel="formsort"
flowLabel="onboarding"
variantLabel="main"
embedConfig={{
style: {
width: '100%',
height: '100%',
},
}}
/>
</div>
);
Use the separate SecureEmbedFlow component to pass responder data in a POST
body:
import { SecureEmbedFlow } from '@formsort/react-embed';
<SecureEmbedFlow
clientLabel="formsort"
flowLabel="onboarding"
// responderUuid={optionalResponderUuid}
initialAnswers={{
firstName: 'Olivia',
}}
formsortEnv="staging"
// variantRevisionUuid={optionalVariantRevisionUuid}
/>;
responderUuid, initialAnswers, formsortEnv, and variantRevisionUuid are
optional. SecureEmbedFlow does not accept queryParams. It sends
responderUuid and initialAnswers in the POST body. It adds formsortEnv and
variantRevisionUuid to the navigation URL.
It has the same configuration and event props as EmbedFlow.
Events
You can add event listeners to flows like Flowloaded, redirect etc. See all event listeners
Props
| Prop name | Description | Required | Example values |
|---|---|---|---|
| clientLabel | client name | yes | formsort |
| flowLabel | flow name | yes | onboarding |
| variantLabel | variant name | no | main |
| responderUuid | responder uuid to load existing answers for | no | e4923baa-dc2d-4555-813c-a166952292fa |
| formsortEnv | formsort integrations environment label, if not using production | no | staging |
| variantRevisionUuid | variant revision UUID to load a specific revision instead of the latest one | no | 0a3c4f52-1b8e-4d1a-9b6f-3a2e5c7d9f10 |
| queryParams | additional query params, to pre-populate answers in the form | no | [['name', 'Olivia'], ['age', '3']] |
| embedConfig | config passed to the underlying FormsortWebEmbed | no | { style: { height: '100%' } } |
| onFlowLoaded | event listener | no | () => { console.log('flow loaded') } |
| onFlowClosed | event listener | no | () => { console.log('flow closed') } |
| onFlowFinalized | event listener | no | () => { console.log('flow finalized') } |
| onStepLoaded | event listener | no | () => { console.log('step loaded') } |
| onStepCompleted | event listener | no | () => { console.log('step loaded') } |
| onRedirect | event listener | no | (url: string) => { console.log('redirecting to:', url) } |
| onUnauthorized | event listener | no | () => { console.log('ID token is missing or invalid.') } |
SecureEmbedFlow props
SecureEmbedFlow supports clientLabel, flowLabel, variantLabel,
embedConfig, and all event props from EmbedFlow. It also supports these
secure embed props:
| Prop name | Description | Required | Example values |
|---|---|---|---|
| responderUuid | responder UUID sent in the POST body | no | e4923baa-dc2d-4555-813c-a166952292fa |
| initialAnswers | initial answers sent in the POST body | no | { firstName: 'Olivia' } |
| formsortEnv | integrations environment | no | staging |
| variantRevisionUuid | variant revision UUID to load | no | 0a3c4f52-1b8e-4d1a-9b6f-3a2e5c7d9f10 |
Loading a specific variant revision
Use the variantRevisionUuid prop to load a specific variant revision. Don't use it if you want to show the latest variant. Both EmbedFlow and SecureEmbedFlow support it.
import React from 'react';
import EmbedFlow from '@formsort/react-embed';
const EmbedFlowExample: React.FunctionComponent = () => (
<div>
<EmbedFlow
clientLabel="formsort"
flowLabel="onboarding"
variantLabel="main"
variantRevisionUuid="<uuidv4>"
/>
</div>
);