### Install @formsort/web-embed-api with npm

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/README.md

Install the web embed API package using npm.

```shell
npm install @formsort/web-embed-api --save
```

--------------------------------

### Install @formsort/web-embed-api with Yarn

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/README.md

Install the web embed API package using Yarn.

```shell
yarn add @formsort/web-embed-api
```

--------------------------------

### Install @formsort/constants

Source: https://github.com/formsort/oss/blob/master/packages/react-embed/ReactNativeEmbed.md

Install the constants package for Formsort integration. Use npm or yarn.

```bash
npm install @formsort/constants # or yarn add @formsort/constants
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/formsort/oss/blob/master/CONTRIBUTING.md

Run this command to install all dependencies for the sub-packages and create symlinks. Volta is recommended for managing Node.js versions.

```shell
yarn install --frozen-lockfile
```

--------------------------------

### Install @formsort/tsconfig

Source: https://github.com/formsort/oss/blob/master/packages/tsconfig/README.md

Install the shared TypeScript configuration as a development dependency using Yarn.

```shell
yarn add --dev @formsort/tsconfig
```

--------------------------------

### Install Custom Question API

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Install the @formsort/custom-question-api package using either yarn or npm.

```shell
yarn add @formsort/custom-question-api
```

```shell
npm install --save @formsort/custom-question-api
```

--------------------------------

### Install webview_flutter

Source: https://github.com/formsort/oss/blob/master/packages/react-embed/FlutterEmbed.md

Add the webview_flutter package to your Flutter project dependencies.

```bash
flutter pub add webview_flutter
```

--------------------------------

### Install Dependencies for ESLint Config

Source: https://github.com/formsort/oss/blob/master/packages/eslint-config/README.md

Install the @formsort/eslint-config package and its peer dependencies as development dependencies.

```bash
yarn add --dev @formsort/eslint-config eslint-plugin-prefer-arrow eslint-plugin-jsdoc@24 eslint-plugin-prettier eslint-config-prettier eslint-plugin-import prettier eslint-plugin-react @typescript-eslint/eslint-plugin
```

--------------------------------

### loadFlow

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/README.md

Starts loading a Formsort variant or a flow into the initialized embed. If a variant label is not provided, a variant will be chosen based on weights or randomly.

```APIDOC
## loadFlow(clientLabel: string, flowLabel: string, variantLabel?: string, queryParams?: Array<[string, string]>) => void

Starts loading a Formsort variant, or a flow.

Note that `variantLabel` is optional. If it is not provided, a variant will be chosen from the flow:

- Based on weights, if weights are assigned

- At random, if no weights are assigned
```

--------------------------------

### Embedding a flow in React Native via `react-native-webview`

Source: https://context7.com/formsort/oss/llms.txt

This example demonstrates how to embed a Formsort flow within a React Native application using the `react-native-webview` component. It includes a JavaScript snippet to bridge `window.postMessage` to `ReactNativeWebView.postMessage` for communication between the webview and the native app, and shows how to handle flow events.

```APIDOC
## Embedding a flow in React Native via `react-native-webview`

Formsort flows can be embedded in React Native using `react-native-webview`. A JavaScript snippet must be injected to bridge `window.postMessage` to `ReactNativeWebView.postMessage`, and the `@formsort/constants` package is used to identify the message type.

```tsx
import React from 'react';
import { StyleSheet, SafeAreaView } from 'react-native';
import { WebView } from 'react-native-webview';
import { WebEmbedMessage } from '@formsort/constants';

// Bridge postMessage to React Native's native message channel
const injectPostMessage = `
  window.postMessage = (data) => window.ReactNativeWebView.postMessage(JSON.stringify(data));
`;

const flowUrl = 'https://acme.formsort.app/flow/onboarding/variant/main';

export default function App() {
  const onMessage = (event: { nativeEvent: { data: string } }) => {
    const eventData = JSON.parse(event.nativeEvent.data);

    if (eventData.type === WebEmbedMessage.EMBED_EVENT_MSG) {
      switch (eventData.eventType) {
        case 'FlowLoaded':
          console.log('Flow loaded');
          break;
        case 'FlowFinalized':
          console.log('Flow finalized, answers:', eventData.answers);
          break;
        case 'StepCompleted':
          console.log('Step completed:', eventData.stepId);
          break;
        default:
          break;
      }
    }
  };

  return (
    <SafeAreaView style={styles.container}>
      <WebView
        containerStyle={styles.webView}
        source={{ uri: flowUrl }}
        onMessage={onMessage}
        allowsBackForwardNavigationGestures={true}
        injectedJavaScript={injectPostMessage}
      />
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: '#fff', justifyContent: 'center' },
  webView: { flex: 1 },
});
```
```

--------------------------------

### React Native Embed Example

Source: https://github.com/formsort/oss/blob/master/packages/react-embed/ReactNativeEmbed.md

Integrate a Formsort flow into a React Native app using react-native-webview. Handles messages from the flow and allows navigation.

```tsx
import { StyleSheet, SafeAreaView } from 'react-native';
import { WebView } from 'react-native-webview';
import { WebEmbedMessage } from '@formsort/constants'

/**
 * Injects a postMessage function into the webview to allow communication
 */
const injectPostMessage = `
  window.postMessage = (data) => window.ReactNativeWebView.postMessage(JSON.stringify(data));
`;

// replace with your flow url
const flowUrl = 'https://uwymnmujkn.formsort.app/flow/booking-flow-test/variant/B';

export default function App() {

  const onMessage = (event) => {
    const eventData = JSON.parse(event.nativeEvent.data);

    // get messages from the flow
    if (eventData.type === WebEmbedMessage.EMBED_EVENT_MSG) {
      switch(event.data.eventType) {
        case 'FlowCompleted':
          console.log('Flow completed');
          // do something when the flow is completed
          break;
        case 'FlowStarted':
          console.log('Flow started');
          // do something when the flow is started
          break;
        default:
          break;
      }
    }
  }

  return (
    <SafeAreaView style={[styles.container]}> 
      <WebView
        containerStyle={styles.webView}
        source={{ uri: flowUrl }}
        onMessage={onMessage}
        allowsBackForwardNavigationGestures={true}
        injectedJavaScript={injectPostMessage}
      />
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    justifyContent: 'center',
  },
  webView: {
    flex: 1,
  }
});

```

--------------------------------

### Get Custom Question Answer Value

Source: https://context7.com/formsort/oss/llms.txt

Use `getAnswerValue<T>()` to retrieve the current answer for a custom question. Call this on mount to restore previously entered values, for example, when the user navigates back.

```ts
import { getAnswerValue } from '@formsort/custom-question-api';

// In your custom question's initialization code:
async function initialize() {
  const currentValue = await getAnswerValue<string>();
  if (currentValue !== undefined) {
    // Restore the previously entered value
    (document.getElementById('my-input') as HTMLInputElement).value = currentValue;
  }
}

initialize();

```

--------------------------------

### Set Question Size with React

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Example of using `setQuestionSize` within a React component to dynamically set the question's dimensions based on its rendered element.

```typescript
import React, { useEffect, useRef } from 'react';
import { setQuestionSize } from '@formsort/custom-question-api';

const MyCustomComponent = () => {
  const containerElRef = useRef<HTMLDivElement>();

  useEffect(() => {
    const containerEl = containerElRef.current;
    if (!containerEl) {
      return;
    }
    setQuestionSize(containerEl.offsetWidth, containerEl.offsetHeight);
  }, []);

  return (
    <div ref={containerElRef}>
      <h1>My custom component</h1>
    </div>
  );
};

```

--------------------------------

### Get All Answer Values

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Retrieves all answers provided by the recipient so far. The keys are the variable names defined in Formsort.

```typescript
getAllAnswerValues() => Promise<{ [key: string]: any }>
```

```typescript
getAllAnswerValues() => Promise<{ [key: string]: any}>
```

--------------------------------

### Basic EmbedFlow Usage in React

Source: https://github.com/formsort/oss/blob/master/packages/react-embed/README.md

Demonstrates how to use the EmbedFlow component to embed a Formsort flow in a React application. Ensure you have installed the package.

```tsx
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>
);
```

--------------------------------

### Get All Answer Values with getAllAnswerValues()

Source: https://context7.com/formsort/oss/llms.txt

Retrieves a promise that resolves to a key/value map of all answers collected in the flow. Keys correspond to variable names configured in Formsort studio.

```typescript
import { getAllAnswerValues } from '@formsort/custom-question-api';

async function prefillFromContext() {
  const allAnswers = await getAllAnswerValues();
  // allAnswers = { first_name: 'Jane', email: 'jane@example.com', age: 28 }

  if (allAnswers['first_name']) {
    document.getElementById('greeting')!.textContent =
      `Hello, ${allAnswers['first_name']}!`;
  }
}

prefillFromContext();
```

--------------------------------

### Embedding a flow in Flutter via `webview_flutter`

Source: https://context7.com/formsort/oss/llms.txt

This example shows how to embed a Formsort flow in a Flutter application using the `webview_flutter` package. It includes JavaScript injection to establish a communication channel between the webview and the Flutter app, enabling the app to receive flow events.

```APIDOC
## Embedding a flow in Flutter via `webview_flutter`

Formsort flows can be embedded in Flutter apps using `webview_flutter`. JavaScript injection bridges `window.postMessage` to a Flutter channel so the app can receive flow events.

```dart
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';
import 'dart:convert';

// Special prefix that identifies Formsort embed event messages
const String EMBED_EVENT_MSG = 'ƒ_wee';

class FormsortFlowPage extends StatefulWidget {
  const FormsortFlowPage({super.key});
  @override
  State<FormsortFlowPage> createState() => _FormsortFlowPageState();
}

class _FormsortFlowPageState extends State<FormsortFlowPage> {
  late final WebViewController controller;

  final flowUrl =
      'https://acme.formsort.app/flow/onboarding/variant/main';

  // Patch window.postMessage to route through the Flutter channel
  final String setUpJSWebViewMessaging = """;
    window.FlutterWebView = true;
    window.postMessage = function(data) {
      FlutterChannel.postMessage(JSON.stringify(data));
    };
  """;

  @override
  void initState() {
    super.initState();
    controller = WebViewController()
      ..loadRequest(Uri.parse(flowUrl))
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..addJavaScriptChannel('FlutterChannel', onMessageReceived: (event) {
        final eventData = jsonDecode(event.message);
        if (eventData['type'] == EMBED_EVENT_MSG) {
          switch (eventData['eventType']) {
            case 'FlowLoaded':
              print('Flow loaded');
              break;
            case 'FlowFinalized':
              print('Flow finalized: ${eventData['answers']}');
              break;
            default:
              break;
          }
        }
      })
      ..setNavigationDelegate(NavigationDelegate(
        onPageFinished: (_) => controller.runJavaScript(setUpJSWebViewMessaging),
      ));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(body: WebViewWidget(controller: controller));
  }
}
```
```

--------------------------------

### Get Answer Value

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Retrieves the current value of the answer for this question. Optionally specify the type with a generic parameter. The value may be undefined.

```typescript
getAnswerValue() => Promise<any>
```

```typescript
getAnswerValue<string>();
```

--------------------------------

### Get Semantic Answer Value

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Retrieves a specific semantic answer value (e.g., responder_email). This allows looking up answers by their meaning, not just variable name.

```typescript
getSemanticAnswerValue(semanticType: AnswerSemanticType) => Promise<any>
```

--------------------------------

### Project Configuration (.env file)

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/examples/formsort-embed-example-lit/README.md

Configure your Formsort integration by setting environment variables in the .env file. This includes your client ID, flow ID, and variant name. Optionally, specify a custom Formsort origin.

```env
CLIENT = my-client
FLOW = first-flow
VARIANT = main
```

--------------------------------

### getResponderUuid

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Gets the current responder's UUID, which can be used for external lookups.

```APIDOC
## getResponderUuid

### Description
Retrieves the unique identifier for the current responder.

### Method Signature
```typescript
getResponderUuid(): Promise<string>
```

### Returns
- `Promise<string>`: A promise that resolves to the responder's UUID.
```

--------------------------------

### Configure ESLint with @formsort/eslint-config

Source: https://github.com/formsort/oss/blob/master/packages/eslint-config/README.md

Set up your project's .eslintrc.js file to extend the shared ESLint configuration.

```javascript
module.exports = {
  extends: "@formsort/eslint-config"
};
```

--------------------------------

### Get Responder UUID

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Retrieves the unique identifier for the current responder. Useful for external lookups.

```typescript
getResponderUuid() => Promise<string>
```

```typescript
getResponderUuid() => Promise<string>
```

--------------------------------

### Restart Flow with Query Parameter

Source: https://github.com/formsort/oss/blob/master/packages/react-embed/ReactNativeEmbed.md

Append '?discardAnswers=true' to the flow URL to restart the flow every time the user returns.

```tsx
const flowUrl = 'https://uwymnmujkn.formsort.app/flow/booking-flow-test/variant/B?discardAnswers=true';
```

--------------------------------

### Development Configuration

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/README.md

Configure the Formsort Web Embed to point to a different flow server during development by setting the 'origin' option in the configuration object.

```APIDOC
## Development Configuration

By default, the web embed accesses the production formsort servers. If you would like to point to another flow server, set `origin` in the config to the correct base URL, for example:

```ts
FormsortWebEmbed(document.body, { origin: 'http://localhost:4040' });
```
```

--------------------------------

### Add ESLint Scripts to package.json

Source: https://github.com/formsort/oss/blob/master/packages/eslint-config/README.md

Include 'format' and 'lint' scripts in your package.json for convenient code formatting and linting.

```json
{
  "scripts": {
    "format": "eslint --ext .ts,.tsx src --fix",
    "lint": "eslint --ext .ts,.tsx src"
  }
}
```

--------------------------------

### Initialize FormsortWebEmbed

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/README.md

Initialize the Formsort embed instance by providing the root HTML element where the iframe will be appended.

```typescript
const embed = FormsortWebEmbed(document.body);
```

--------------------------------

### loadFlow(clientLabel, flowLabel, variantLabel?, queryParams?)

Source: https://context7.com/formsort/oss/llms.txt

Loads a specific Formsort flow and optional variant into the initialized embed. Query parameters can be used for pre-population or specific revision loading.

```APIDOC
## loadFlow(clientLabel, flowLabel, variantLabel?, queryParams?)

### Description
Starts loading a specific Formsort flow (and optional variant) inside the previously initialized iframe. If `variantLabel` is omitted, a variant is chosen by weight or at random. Query params can be used to pre-populate answers or load a specific variant revision.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **clientLabel** (string) - Required - The client label for the Formsort flow.
- **flowLabel** (string) - Required - The label of the flow to load.
- **variantLabel** (string) - Optional - The label of the specific variant to load. If omitted, a variant is chosen by weight or at random.
- **queryParams** (Array<[string, string]>) - Optional - An array of key-value pairs for query parameters. Used to pre-populate answers or load specific revisions (e.g., `['name', 'Jane Doe']`, `['variantRevisionUuid', 'b3f1a2c4-...']`).

### Request Example
```javascript
// Load a specific variant
embed.loadFlow('acme', 'onboarding', 'main');

// Load with pre-populated answers and environment override
embed.loadFlow('acme', 'onboarding', 'main', [
  ['name', 'Jane Doe'],
  ['email', 'jane@example.com'],
  ['formsortEnv', 'staging'],
  // Load a pinned revision (avoid showing latest):
  // ['variantRevisionUuid', 'b3f1a2c4-...'],
]);
```

### Response
#### Success Response (200)
None (This method performs an action and does not return data directly).
```

--------------------------------

### Initialize Formsort Web Embed

Source: https://context7.com/formsort/oss/llms.txt

Creates and appends a Formsort iframe to a specified DOM element. Configure iframe behavior, styling, and authentication. Use `useHistoryAPI` for SPA compatibility and `autoHeight` for dynamic resizing.

```typescript
import FormsortWebEmbed from '@formsort/web-embed-api';

// Basic initialization with configuration
const embed = FormsortWebEmbed(document.getElementById('form-container')!, {
  useHistoryAPI: true,       // Use window.history.pushState for redirects (SPA-friendly)
  autoHeight: true,          // Auto-resize iframe to match flow content height
  iframeTitle: 'Onboarding', // Accessibility title for the iframe
  iframeAllow: 'camera;',    // Permissions policy (e.g. for camera access)
  style: {
    width: '100%',
    height: '600px',
  },
  authentication: {
    idToken: 'eyJhbGciOiJSUzI1NiIsInR5cCI6...', // JWT for authenticated flows
  },
  // origin: 'https://acme-flow.com', // Uncomment to use a custom domain
});
```

--------------------------------

### Get Responder UUID with getResponderUuid()

Source: https://context7.com/formsort/oss/llms.txt

Returns a promise for the unique ID of the current form responder. This ID is useful for performing external lookups against your own databases.

```typescript
import { getResponderUuid } from '@formsort/custom-question-api';

async function loadExternalData() {
  const uuid = await getResponderUuid();
  // uuid = 'e4923baa-dc2d-4555-813c-a166952292fa'

  const response = await fetch(`/api/users/${uuid}/preferences`);
  const prefs = await response.json();
  applyPreferences(prefs);
}

loadExternalData();
```

--------------------------------

### Configure Package for Public NPM Registry

Source: https://github.com/formsort/oss/blob/master/CONTRIBUTING.md

Add this configuration to your package.json to make the package public on the npm registry. This is required when adding new public packages.

```json
{
  "publishConfig": {
    "access": "public"
  }
}
```

--------------------------------

### Import Helper Functions

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Import necessary helper functions from the @formsort/custom-question-api library into your custom question implementation.

```javascript
import {
  getAnswerValue,
  setAnswerValue,
  clearAnswerValue,
  getSemanticAnswerValue,
  getAllAnswerValues,
  getResponderUuid,
  setQuestionSize,
  setDisableBackNavigation,
  setAutoHeight,
} from '@formsort/custom-question-api';
```

--------------------------------

### Get Semantic Answer Value with getSemanticAnswerValue()

Source: https://context7.com/formsort/oss/llms.txt

Fetches an answer by its semantic type, such as 'responder_email'. This is more robust than using variable names as Formsort maps semantic types to variables.

```typescript
import { getSemanticAnswerValue } from '@formsort/custom-question-api';

async function loadUserContext() {
  const email = await getSemanticAnswerValue<string>('responder_email');
  const firstName = await getSemanticAnswerValue<string>('responder_first_name');
  const phone = await getSemanticAnswerValue<string>('responder_phone');

  // Supported semantic types:
  // 'responder_email' | 'responder_first_name' | 'responder_last_name'
  // 'responder_phone' | 'responder_dob' | 'responder_mailing_address'
  // 'responder_user_id' | 'responder_marketing_consent' | 'responder_other_pii'

  console.log(`Welcome ${firstName} (${email})`);
}

loadUserContext();
```

--------------------------------

### Customizing Flow Behavior with URL Parameter

Source: https://github.com/formsort/oss/blob/master/packages/react-embed/FlutterEmbed.md

Append '?discardAnswers=true' to the flow URL to ensure the flow restarts every time a user returns to it.

```dart
final flowUrl = 'https://formsorttemplatesdemo.formsort.app/flow/template-patient-onboarding-demo/variant/patient-onboarding-customization?discardAnswers=true';
```

--------------------------------

### FormsortWebEmbed Initialization

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/README.md

Initializes a Formsort iframe as a child of the provided root element. Configuration options can be passed to customize the embed behavior and appearance.

```APIDOC
## FormsortWebEmbed(rootEl: HTMLElement, config?: IFormsortWebEmbedConfig)

Initializes a Formsort iframe as a child of the `rootEl` provided.

```ts
const embed = FormsortWebEmbed(document.body);
```

The optional `config` object has the following interface:

```ts
interface IFormsortWebEmbedConfig {
  useHistoryAPI?: boolean; // Default: false
  /**
   * iframe title attribute for accessibility
   */
  iframeTitle?: string;
  /**
   * iframe allow attribute for permissions
   * e.g. "camera;"
   */
  iframeAllow?: string;
  autoHeight?: boolean; // Default: false
  style?: {
    width?: CSSStyleDeclaration['width'];
    height?: CSSStyleDeclaration['height'];
  };
  authentication?: {
    idToken?: string; // ID Token for authenticated flows
  };
  origin?: string; // optional -- use if you want to load your flow in a custom damain. e.g. https://acme-flow.com
}
```

#### `config` properties

- `useHistoryAPI`: When redirecting, should we use the HTML5 History API (namely, `window.pushState`), or just change the URL in its entirety?

  Helpful if you have a single-page app and want to change the container's URL without reloading the entire page. Note that you'll have to listen to the `popstate` event on the embedding `window` to detect this navigation.

- `autoHeight`: Should the embedding `<iframe>` resize so that it matches the content of the currently loaded flow?

- `style`: CSS properties to be applied to the iframe container.

- `iframeTitle`: Optional string to set the iframe's title attribute for accessibility. If not provided, the embed will attempt to set a title from the flow's document title when available.

- `iframeAllow`: Optional string to set the iframe's allow attribute for permissions (for example: `"camera;"`).

- `authentication.idToken`: When the Flow requires an ID token, this can be used to provide it.

- `origin`: When present, loads the flow from your custom domain instead of the default formsort domain.
```

--------------------------------

### Process Web Embed Messages in React Native

Source: https://context7.com/formsort/oss/llms.txt

The `WebEmbedMessage` enum helps discriminate message types sent between the Formsort iframe and the host page. This example shows how to handle these messages in a React Native `onMessage` handler.

```typescript
import { WebEmbedMessage } from '@formsort/constants';

// In React Native onMessage handler:
const onMessage = (event: { nativeEvent: { data: string } }) => {
  const data = JSON.parse(event.nativeEvent.data);

  switch (data.type) {
    case WebEmbedMessage.EMBED_EVENT_MSG:
      // Analytics event (FlowLoaded, StepCompleted, etc.)
      console.log('Analytics event:', data.eventType, data.answers);
      break;
    case WebEmbedMessage.EMBED_REDIRECT_MSG:
      // Flow is requesting a redirect
      console.log('Redirect to:', data.payload);
      break;
    case WebEmbedMessage.EMBED_RESIZE_MSG:
      // Flow is requesting a resize
      console.log('Resize to:', data.payload.width, data.payload.height);
      break;
    case WebEmbedMessage.EMBED_TOKEN_REQUEST_MSG:
      // Flow needs an auth token
      console.log('Token request:', data.payload);
      break;
  }
};
```

--------------------------------

### `getAnswerValue<T>()` — Get the current value of this question's answer

Source: https://context7.com/formsort/oss/llms.txt

This function retrieves the current answer value for a custom question. It returns a `Promise` that resolves to the answer value, which is useful for restoring previously entered data when the user navigates back.

```APIDOC
## `getAnswerValue<T>()` — Get the current value of this question's answer

Returns a `Promise` resolving to the current answer value (or `undefined`) for the custom question. Call this on mount to restore a previously entered value (e.g., when user navigates back).

```ts
import { getAnswerValue } from '@formsort/custom-question-api';

// In your custom question's initialization code:
async function initialize() {
  const currentValue = await getAnswerValue<string>();
  if (currentValue !== undefined) {
    // Restore the previously entered value
    (document.getElementById('my-input') as HTMLInputElement).value = currentValue;
  }
}

initialize();
```
```

--------------------------------

### Environment Variables for Formsort Embedding

Source: https://github.com/formsort/oss/blob/master/packages/react-embed/examples/event-log/README.md

Configure these environment variables in a .env file at the project root to specify the Formsort client, flow, and variant.

```bash
CLIENT=my-client
FLOW=first-flow
VARIANT=main
```

--------------------------------

### setAutoHeight

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Configures a ResizeObserver to automatically adjust the question's container size to match its content height, preventing internal scrolling.

```APIDOC
## setAutoHeight

### Description
Enables automatic adjustment of the question's container height to fit its content, eliminating the need for internal scrollbars.

### Method Signature
```typescript
setAutoHeight(enabled: boolean): void
```

### Parameters
- `enabled` (boolean): `true` to enable auto-height, `false` to disable it.
```

--------------------------------

### Loading a specific variant revision

Source: https://github.com/formsort/oss/blob/master/packages/react-embed/README.md

Demonstrates how to use query parameters to load a specific variant revision of a Formsort flow instead of the latest one.

```APIDOC
## Loading a specific variant revision

### Description

You can use query parameters to load a specific variant revision. This is useful when you need to test or deploy a particular version of your flow. Do not use this if you intend to show the latest variant.

### Example Usage

```tsx
import React from 'react';
import EmbedFlow from '@formsort/react-embed';

const EmbedFlowExample: React.FunctionComponent = () => (
  <div>
    <EmbedFlow
      clientLabel="formsort"
      flowLabel="onboarding"
      variantLabel="main"
      queryParams={['variantRevisionUuid', '<uuidv4>']}
    />
  </div>
);
```
```

--------------------------------

### FormsortWebEmbed(rootEl, config?)

Source: https://context7.com/formsort/oss/llms.txt

Initializes a Formsort iframe embed within a specified root element. The optional config object allows customization of iframe behavior, styling, authentication, and more.

```APIDOC
## FormsortWebEmbed(rootEl, config?)

### Description
Creates and appends a Formsort iframe as a child of `rootEl`. Returns an embed instance with methods to load flows, manage size, add/remove event listeners, and clean up. The optional `config` object controls iframe behavior, styling, authentication, and origin.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **rootEl** (HTMLElement) - Required - The root DOM element to append the iframe to.
- **config** (object) - Optional - Configuration object for the embed.
  - **useHistoryAPI** (boolean) - Optional - Use window.history.pushState for redirects (SPA-friendly).
  - **autoHeight** (boolean) - Optional - Auto-resize iframe to match flow content height.
  - **iframeTitle** (string) - Optional - Accessibility title for the iframe.
  - **iframeAllow** (string) - Optional - Permissions policy for the iframe (e.g., 'camera;').
  - **style** (object) - Optional - CSS styles to apply to the iframe.
    - **width** (string) - Optional - CSS width of the iframe.
    - **height** (string) - Optional - CSS height of the iframe.
  - **authentication** (object) - Optional - Authentication configuration.
    - **idToken** (string) - Required if authentication is used - JWT for authenticated flows.
  - **origin** (string) - Optional - Custom domain for the Formsort flow.

### Request Example
```javascript
import FormsortWebEmbed from '@formsort/web-embed-api';

const embed = FormsortWebEmbed(document.getElementById('form-container')!, {
  useHistoryAPI: true,
  autoHeight: true,
  iframeTitle: 'Onboarding',
  iframeAllow: 'camera;',
  style: {
    width: '100%',
    height: '600px',
  },
  authentication: {
    idToken: 'eyJhbGciOiJSUzI1NiIsInR5cCI6...', 
  },
  // origin: 'https://acme-flow.com',
});
```

### Response
#### Success Response (200)
- **embedInstance** (object) - An instance of the embed with methods to control the flow.
```

--------------------------------

### Development Configuration: Custom Origin

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/README.md

Configure the web embed to access a different Formsort flow server by setting the `origin` option in the configuration object. This is useful for development or pointing to a self-hosted instance.

```typescript
FormsortWebEmbed(document.body, { origin: 'http://localhost:4040' });
```

--------------------------------

### setSize

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/README.md

Dynamically sets the CSS width and height of the embed. The iframe itself can also be styled directly using CSS selectors.

```APIDOC
## setSize(width: number, height: number) => void

Set the CSS size of the embed.

You may also style the embed's iframe using CSS - it is the iframe child of the `rootEl`, so you'd use the selector `#rootEl > iframe`.
```

--------------------------------

### Environment Variables for Google OAuth

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/examples/authenticated-flow/README.md

Configure these environment variables in your .env file to set up Google OAuth for your authenticated Formsort Flow.

```env
GOOGLE_CLIENT_ID=your-client-id
CLIENT_LABEL=my-client
FLOW_LABEL=first-flow
VARIANT_LABEL=main
```

--------------------------------

### setQuestionSize

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Manually sets the width and height of the question within Formsort. This should not be used if `setAutoHeight` is enabled. Units can be pixels (default) or specified as strings (e.g., '2em', '100%').

```APIDOC
## setQuestionSize

### Description
Manually sets the dimensions (width and height) of the custom question component within the Formsort interface.

### Method Signature
```typescript
setQuestionSize(width?: number | string, height?: number | string): void
```

### Parameters
- `width` (number | string, optional): The desired width. Defaults to pixels if a number is provided. Can be a string with units (e.g., '100%', '50px').
- `height` (number | string, optional): The desired height. Defaults to pixels if a number is provided. Can be a string with units (e.g., '100%', '50px').

### Example Usage (React)
```typescript
import React, { useEffect, useRef } from 'react';
import { setQuestionSize } from '@formsort/custom-question-api';

const MyCustomComponent = () => {
  const containerElRef = useRef<HTMLDivElement>();

  useEffect(() => {
    const containerEl = containerElRef.current;
    if (!containerEl) {
      return;
    }
    setQuestionSize(containerEl.offsetWidth, containerEl.offsetHeight);
  }, []);

  return (
    <div ref={containerElRef}>
      <h1>My custom component</h1>
    </div>
  );
};
```
```

--------------------------------

### setSize(width, height)

Source: https://context7.com/formsort/oss/llms.txt

Programmatically resizes the embed iframe to the specified dimensions.

```APIDOC
## setSize(width, height)

### Description
Programmatically sets the CSS width and height of the embed iframe. Accepts numbers (treated as pixels) or CSS strings. Not needed if `autoHeight: true` is set in config.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **width** (number | string) - Required - The desired width of the iframe. Can be a number (pixels) or a CSS string (e.g., '100%').
- **height** (number | string) - Required - The desired height of the iframe. Can be a number (pixels) or a CSS string (e.g., '600px').

### Request Example
```javascript
const embed = FormsortWebEmbed(document.getElementById('form-container')!);
embed.loadFlow('acme', 'onboarding', 'main');

// Resize to fill the viewport
embed.setSize('100vw', '100vh');

// Or use pixel values
embed.setSize('800', '600');
```

### Response
#### Success Response (200)
None (This method performs an action and does not return data directly).
```

--------------------------------

### Event Listeners

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/README.md

Allows you to attach event listeners to the embed to react to various flow states, such as loading, finalization, closing, or step changes. Event listeners receive user answers when the flow is embedded in a whitelisted domain.

```APIDOC
## embed.addEventListener(eventName: key of IEventMap, fn: IEventMap[eventName]) => void

If the flow is embedded in a whitelisted domain, each event listener will be passed the user's answers.

The events include:

#### FlowLoaded `(answers?: { [key: string]: any } ) => void`

Set a callback function to be called when the Formsort flow has loaded completely.

Note that this is more accurate than listening for the iframe's `load` event, as this is sent from within the Formsort application code and not merely when the DOM is loaded.

You can listen for this to do things like hide the frame container, or display a loading indicator, until everything is loaded to ensure a seamless initial experience.

```ts
const embed = FormsortWebEmbed(document.body);
embed.addEventListener('FlowLoaded', () => {
  console.log('Flow has loaded!');
});
embed.loadFlow('formsort', 'onboarding', 'main');
```

#### FlowFinalized `(answers?: { [key: string]: any }) => void`

Set a callback to be called when the flow is complete, meaning the user has finished all of the steps available to them.

Useful for performing an action after the flow is complete, such as displaying a congratulations or starting a payment process.

#### FlowClosed `(answers?: { [key: string]: any }) => void`

Set a callback to be called when the user abandons the flow before finalizing it.

Note that this is only possible if your style set defines a close button.

#### StepLoaded `(answers?: { [key: string]: any }) => void`

Set a callback to be called when a new step is loaded.

This will happen once after the flow is loaded, if the user hasn't previously completed the flow. Subsequently, this event will happen following the completion of each step, except for the completion of the final step.
```

--------------------------------

### `setAutoHeight(enabled)`

Source: https://context7.com/formsort/oss/llms.txt

Enables or disables automatic resizing of the custom question to match its body height. When enabled, a `ResizeObserver` monitors the body height and reports changes to Formsort, preventing scrollbars within the flow. This is mutually exclusive with `setQuestionSize`.

```APIDOC
## `setAutoHeight(enabled)`

### Description
Auto-resize custom question to match body height. Attaches (or detaches) a `ResizeObserver` on `document.body` that automatically reports the document height to the parent Formsort flow whenever it changes. This prevents scrollbars within Formsort in most cases. Mutually exclusive with `setQuestionSize`.

### Parameters
#### Path Parameters
- **enabled** (boolean) - Required - `true` to enable auto-height, `false` to disable.

### Request Example
```ts
import { setAutoHeight } from '@formsort/custom-question-api';

// Enable on mount — Formsort will track height changes automatically
setAutoHeight(true);

// Disable if you need to take manual control
function switchToManualSizing() {
  setAutoHeight(false);
  // Now safe to call setQuestionSize(...)
}
```
```

--------------------------------

### `setQuestionSize(width?, height?)`

Source: https://context7.com/formsort/oss/llms.txt

Manually sets the dimensions of the custom question, sending a resize message to the parent Formsort flow. This is useful when the dimensions are known upfront and cannot be used if `setAutoHeight` is enabled.

```APIDOC
## `setQuestionSize(width?, height?)`

### Description
Manually set the custom question's dimensions. Sends a resize message to the parent Formsort flow to allocate the specified space for this question. Use when you know the dimensions up front. Cannot be used while `setAutoHeight` is enabled. Numbers are treated as pixels; strings can use any CSS unit.

### Parameters
#### Path Parameters
- **width** (number | string) - Optional - The desired width of the question. Can be a number (pixels) or a string with a CSS unit.
- **height** (number | string) - Optional - The desired height of the question. Can be a number (pixels) or a string with a CSS unit.

### Request Example
```tsx
import React, { useEffect, useRef } from 'react';
import { setQuestionSize } from '@formsort/custom-question-api';

const MyCustomQuestion: React.FC = () => {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const el = containerRef.current;
    if (!el) return;
    // Measure after render and report to Formsort
    setQuestionSize(el.offsetWidth, el.offsetHeight);
    // Or use CSS units:
    // setQuestionSize('100%', '300px');
  }, []);

  return (
    <div ref={containerRef}>
      <h1>Custom Question</h1>
    </div>
  );
};

export default MyCustomQuestion;
```
```

--------------------------------

### Listen to Formsort Flow Events with addEventListener

Source: https://context7.com/formsort/oss/llms.txt

Register callbacks for Formsort flow lifecycle events like FlowLoaded, StepLoaded, and FlowFinalized. Callbacks receive responder answers and other relevant data. Ensure the embed instance is initialized before adding listeners.

```typescript
const embed = FormsortWebEmbed(document.getElementById('form-container')!); // FlowLoaded — fires when flow is fully initialized (more reliable than iframe 'load') embed.addEventListener('FlowLoaded', ({ answers, responder }) => { console.log('Flow ready. Responder UUID:', responder?.responderUuid); document.getElementById('spinner')!.style.display = 'none'; }); // StepLoaded — fires each time a new step is displayed embed.addEventListener('StepLoaded', ({ answers, stepIndex }) => { console.log(`Step ${stepIndex} loaded. Answers so far:`, answers); }); // StepCompleted — fires when a step is submitted embed.addEventListener('StepCompleted', ({ answers, stepId }) => { console.log(`Step "${stepId}" completed:`, answers); }); // ResponderStateUpdated — fires on each save (correlates with StepCompleted unless autoSave is on) embed.addEventListener('ResponderStateUpdated', ({ answers }) => { console.log('Answers saved to backend:', answers); }); // FlowFinalized — fires when all steps are complete embed.addEventListener('FlowFinalized', ({ answers }) => { console.log('Form complete! Final answers:', answers); document.getElementById('thank-you')!.style.display = 'block'; }); // FlowClosed — fires when user clicks close button (requires close button in style set) embed.addEventListener('FlowClosed', () => { console.log('User abandoned the flow.'); }); // redirect — intercept redirects; return { cancel: true } to suppress default navigation embed.addEventListener('redirect', ({ url, answers }) => { console.log('Flow wants to redirect to:', url); window.history.pushState({}, '', url); // SPA navigation return { cancel: true }; // prevent default redirect }); // unauthorized — fires when flow requires auth but idToken is missing/invalid embed.addEventListener('unauthorized', () => { console.error('Auth token invalid. Prompting re-login...'); window.location.href = '/login'; }); embed.loadFlow('acme', 'onboarding', 'main');
```

--------------------------------

### Load a Formsort Flow

Source: https://github.com/formsort/oss/blob/master/packages/web-embed-api/README.md

Load a specific Formsort flow or variant by providing its client and flow labels. A variant label is optional and will be selected based on weights or randomly if not provided.

```typescript
embed.loadFlow('formsort', 'onboarding', 'main');
```

--------------------------------

### Load Formsort Flow into Embed

Source: https://context7.com/formsort/oss/llms.txt

Loads a specific Formsort flow and variant into the initialized iframe. Supports pre-populating answers and specifying query parameters for environment overrides or specific revision loading.

```typescript
// Load a specific variant
embed.loadFlow('acme', 'onboarding', 'main');

// Load with pre-populated answers and environment override
embed.loadFlow('acme', 'onboarding', 'main', [
  ['name', 'Jane Doe'],
  ['email', 'jane@example.com'],
  ['formsortEnv', 'staging'],
  // Load a pinned revision (avoid showing latest):
  // ['variantRevisionUuid', 'b3f1a2c4-...'],
]);
```

--------------------------------

### Set Auto Height

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Configures a ResizeObserver to automatically adjust the question's containing size to match its body height, preventing internal scrolling.

```typescript
setAutoHeight(enabled: boolean) => void
```

--------------------------------

### Set Question Size

Source: https://github.com/formsort/oss/blob/master/packages/custom-question-api/README.md

Manually sets the width and height of the question within Formsort. Use this when auto-height is not enabled and dimensions are not known beforehand.

```typescript
setQuestionSize(width?: number | string, height?: number | string) => void
```

--------------------------------

### addEventListener(eventName, fn)

Source: https://context7.com/formsort/oss/llms.txt

Registers a callback function to listen for specific Formsort flow lifecycle events. Multiple listeners can be attached to the same event.

```APIDOC
## addEventListener(eventName, fn) — Listen to flow lifecycle events

Registers a callback for a named Formsort flow event. When the embed is inside a whitelisted domain, callbacks receive the responder's current `answers` object. Multiple listeners can be added for the same event.

### Parameters
#### Path Parameters
- **eventName** (string) - Required - The name of the event to listen for (e.g., 'FlowLoaded', 'StepLoaded').
- **fn** (function) - Required - The callback function to execute when the event is triggered. It receives an event object with relevant data.

### Event Data
- **FlowLoaded**: `{ answers: object, responder: { responderUuid: string } }`
- **StepLoaded**: `{ answers: object, stepIndex: number }`
- **StepCompleted**: `{ answers: object, stepId: string }`
- **ResponderStateUpdated**: `{ answers: object }`
- **FlowFinalized**: `{ answers: object }`
- **FlowClosed**: `{}`
- **redirect**: `{ url: string, answers: object }` - Returning `{ cancel: true }` suppresses default navigation.
- **unauthorized**: `{}`

### Example
```javascript
const embed = FormsortWebEmbed(document.getElementById('form-container')!);

embed.addEventListener('FlowLoaded', ({ answers, responder }) => {
  console.log('Flow ready. Responder UUID:', responder?.responderUuid);
});

embed.addEventListener('StepLoaded', ({ answers, stepIndex }) => {
  console.log(`Step ${stepIndex} loaded. Answers so far:`, answers);
});

embed.addEventListener('FlowFinalized', ({ answers }) => {
  console.log('Form complete! Final answers:', answers);
});

embed.loadFlow('acme', 'onboarding', 'main');
```
```

--------------------------------

### Basic Flutter Embed Usage

Source: https://github.com/formsort/oss/blob/master/packages/react-embed/FlutterEmbed.md

Integrates a Formsort flow into a Flutter app using WebViewWidget. It sets up JavaScript messaging to receive events from the flow.

```dart
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';
import 'dart:convert';

// This message type is prefixed by a special character to avoid collisions with
// other messages that may be sent from the webview.
// so just copy this to avoid errors
const String EMBED_EVENT_MSG = 'ƒ_wee';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});
  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  late final WebViewController controller;
  final flowUrl =
      'https://formsorttemplatesdemo.formsort.app/flow/template-patient-onboarding-demo/variant/patient-onboarding-customization';

  final String setUpJSWebViewMessaging = """
    window.FlutterWebView = true;
    window.postMessage = function(data) {
      FlutterChannel.postMessage(JSON.stringify(data));
    };
  """;
  @override
  void initState() {
    super.initState();
    controller = WebViewController()
      ..loadRequest(
        Uri.parse(flowUrl),
      )
      ..setJavaScriptMode(JavaScriptMode.unrestricted) // enable javascript
      ..addJavaScriptChannel('FlutterChannel', onMessageReceived: (event) {
        final eventData = jsonDecode(event.message);
        if (eventData['type'] == EMBED_EVENT_MSG) {
          // get messages from the flow
          switch (eventData['eventType']) {
            case 'FlowCompleted':
              print('Flow completed');
              break;
            case 'FlowLoaded':
              print('Flow loaded');
              break;
            default:
              break;
          }
        }
      })
      ..setNavigationDelegate(NavigationDelegate(onPageFinished: (ulr) {
        controller.runJavaScript(setUpJSWebViewMessaging);
      }));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: WebViewWidget(
        controller: controller,
      ),
    );
  }
}

```

--------------------------------

### Set Custom Question Size with setQuestionSize()

Source: https://context7.com/formsort/oss/llms.txt

Manually sets the dimensions for a custom question. Use this when the size is known upfront. It accepts pixel values or CSS units and cannot be used with setAutoHeight enabled.

```tsx
import React, { useEffect, useRef } from 'react';
import { setQuestionSize } from '@formsort/custom-question-api';

const MyCustomQuestion: React.FC = () => {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const el = containerRef.current;
    if (!el) return;
    // Measure after render and report to Formsort
    setQuestionSize(el.offsetWidth, el.offsetHeight);
    // Or use CSS units:
    // setQuestionSize('100%', '300px');
  }, []);

  return (
    <div ref={containerRef}>
      <h1>Custom Question</h1>
    </div>
  );
};

export default MyCustomQuestion;
```