> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Form Screens

> Complete reference for all form module screens and their events

## Overview

The Form module consists of 13 screens that guide users through the verification flow. Each screen emits events following a consistent naming pattern.

## Event Naming Convention

All screen events follow the pattern:

```
form:{screen_id}:{stage}
```

For example: `form:welcome:ready`, `form:review:success`, `form:result:pending`

### Event Stages

| Stage      | Description                                                                                                                                                                              | Emitted By                              |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `ready`    | User pressed the screen's CTA (call-to-action) button, completing the screen                                                                                                             | All screens                             |
| `loaded`   | Screen has been rendered and is interactive                                                                                                                                              | All screens                             |
| `failed`   | Screen failed to load or an error occurred                                                                                                                                               | All screens (except result — see below) |
| `success`  | CTA pressed on a SUCCESS-state result screen, or verification succeeded (review with [`customResult`](/docs/sdk-reference/form-module/configuration#page-configuration-types) only)      | review, result, doc\_upload             |
| `partial`  | CTA pressed on a PARTIAL-state result screen, or partial verification result (review with [`customResult`](/docs/sdk-reference/form-module/configuration#page-configuration-types) only) | review, result                          |
| `pending`  | CTA pressed on a PENDING-state result screen, or verification pending (review with [`customResult`](/docs/sdk-reference/form-module/configuration#page-configuration-types) only)        | review, result                          |
| `back`     | User navigated back from screen                                                                                                                                                          | document                                |
| `navigate` | User navigated to another screen                                                                                                                                                         | document, doc\_upload                   |

### Event Payload

All screen events emit an `EventPayload` object:

```typescript theme={null}
{
  componentName?: string;     // Module name
  provider?: string;          // Provider name ('react')
  inputInfo: {
    name?: string;            // Screen ID (e.g., 'welcome', 'review')
    type?: string;            // Config type ('ocr', 'manual', 'doc_upload')
    documentType?: string;    // Document type if applicable
    index?: number;           // Document index if applicable
  }
}
```

***

## Screen Reference

<Note>
  All examples below assume the SDK has been initialized:

  ```javascript theme={null}
  const sdk = await OneSdk({
    session: { token: 'your-token' },
    recipe: {
      form: {
        provider: {
          name: 'react',
          googleApiKey: 'your-google-api-key'
        }
      }
    }
  });
  ```
</Note>

### Welcome

The first screen shown to users. Introduces the verification process and provides a call-to-action to begin.

**Screen ID:** `welcome`

**Events:**

| Event                 | Description                                |
| --------------------- | ------------------------------------------ |
| `form:welcome:ready`  | User pressed the CTA on the welcome screen |
| `form:welcome:loaded` | Welcome screen has been rendered           |
| `form:welcome:failed` | Welcome screen failed to load              |

**Example:**

```javascript theme={null}
const welcome = sdk.component('form', {
  name: 'WELCOME',
  type: 'manual'
});

welcome.on('form:welcome:loaded', (payload) => {
  console.log('Welcome screen shown');
});

await welcome.mount('#form-container');
```

***

### Start

Entry point screen for certain flows. Allows configuration of the initial verification step.

**Screen ID:** `start`

**Events:**

| Event               | Description                              |
| ------------------- | ---------------------------------------- |
| `form:start:ready`  | User pressed the CTA on the start screen |
| `form:start:loaded` | Start screen has been rendered           |
| `form:start:failed` | Start screen failed to load              |

***

### Consent

Collects user consent for identity verification and data processing.

**Screen ID:** `consent`

**Events:**

| Event                 | Description                               |
| --------------------- | ----------------------------------------- |
| `form:consent:ready`  | User accepted consent and pressed the CTA |
| `form:consent:loaded` | Consent screen has been rendered          |
| `form:consent:failed` | Consent screen failed to load             |

**Example:**

```javascript theme={null}
const consent = sdk.component('form', {
  name: 'CONSENT',
  type: 'manual'
});

consent.on('form:consent:loaded', (payload) => {
  console.log('Consent screen displayed');
});

await consent.mount('#form-container');
```

***

### Document Selection

Allows users to select which identity document(s) they want to use for verification (e.g., driver's licence, passport, national ID, Medicare card). Used in manual and doc\_upload flows.

<Note>
  In OCR mode, the Document Selection screen is a legacy feature tied to headless OCR flows. Modern integrations use the [IDV flow](/docs/sdk-reference/idv-module) for document capture and the form [Review screen](#review) to display extracted data.
</Note>

**Screen ID:** `document`

**Supported Document Types:**

* `DRIVERS_LICENCE` - Driver's licence
* `PASSPORT` - Passport
* `NATIONAL_ID` - National identity card
* `NATIONAL_HEALTH_ID` - National health ID / Medicare card

**Events:**

| Event                    | Description                                                            |
| ------------------------ | ---------------------------------------------------------------------- |
| `form:document:ready`    | User completed document selection and pressed the CTA                  |
| `form:document:loaded`   | Document selection screen has been rendered                            |
| `form:document:failed`   | Document selection screen failed to load                               |
| `form:document:back`     | User navigated back from filling document detail to document selection |
| `form:document:navigate` | User selected a document and is navigating forward                     |

**Example:**

```javascript theme={null}
const document = sdk.component('form', {
  name: 'DOCUMENT',
  type: 'manual',
  numberOfIDs: 2
});

document.on('form:document:loaded', (payload) => {
  console.log('Document selection screen displayed');
});

document.on('form:document:navigate', (payload) => {
  console.log('User selected:', payload.inputInfo.documentType);
});

await document.mount('#form-container');
```

***

### Personal Details

Collects personal information such as name, date of birth, and address.

**Screen ID:** `personal`

**Events:**

| Event                  | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `form:personal:ready`  | User completed personal details and pressed the CTA |
| `form:personal:loaded` | Personal details screen has been rendered           |
| `form:personal:failed` | Personal details screen failed to load              |

**Example:**

```javascript theme={null}
const personal = sdk.component('form', {
  name: 'PERSONAL',
  type: 'manual'
});

personal.on('form:personal:loaded', (payload) => {
  console.log('Personal details form displayed');
});

await personal.mount('#form-container');
```

***

### Review

Displays collected data for user review before submission. In manual mode with [`verify: true`](/docs/sdk-reference/form-module/configuration#page-configuration-types), submits the data for verification and navigates to the appropriate result screen automatically. When [`customResult: true`](/docs/sdk-reference/form-module/configuration#page-configuration-types) is also set, the form emits review-level result events instead of navigating to result screens, giving you full control over result handling.

**Screen ID:** `review`

**Events:**

| Event                 | Description                                              |
| --------------------- | -------------------------------------------------------- |
| `form:review:ready`   | User pressed the CTA on the review screen                |
| `form:review:loaded`  | Review screen has been rendered                          |
| `form:review:failed`  | Entity doesn't pass verification                         |
| `form:review:success` | Verification completed successfully                      |
| `form:review:partial` | Partial match — some data verified, some needs attention |
| `form:review:pending` | Verification submitted but result is pending             |

<Warning>
  **`form:review:failed/success/partial/pending` require [`customResult: true`](/docs/sdk-reference/form-module/configuration#page-configuration-types) in manual mode.**

  These four events are **only emitted when `customResult: true` is set on the review component in manual mode**. When `customResult` is `false` (the default), the form automatically navigates to the configured result screen — these review-level result events are not emitted. In OCR mode, the only review event is `form:review:ready`.

  See [`verify`](/docs/sdk-reference/form-module/configuration#page-configuration-types) and [`customResult`](/docs/sdk-reference/form-module/configuration#page-configuration-types) in the configuration reference.
</Warning>

**Example (with `customResult: true`):**

```javascript theme={null}
const review = sdk.component('form', {
  name: 'REVIEW',
  type: 'manual',
  verify: true,
  customResult: true
});

review.on('form:review:loaded', (payload) => {
  console.log('Review screen displayed');
});

review.on('form:review:success', (payload) => {
  console.log('Verification passed — show custom success UI');
});

review.on('form:review:partial', (payload) => {
  console.log('Partial match — show retry or custom UI');
});

review.on('form:review:pending', (payload) => {
  console.log('Verification pending — show custom pending UI');
});

review.on('form:review:failed', (payload) => {
  console.log('Verification failed — show custom failure UI');
});

await review.mount('#form-container');
```

***

### Loading

Displayed while verification is being processed.

**Screen ID:** `loading`

This screen is managed internally by the form module and typically does not require event handling.

***

### Result

Displays the final verification result to the user. Shows success, failure, partial match, or pending status.

**Screen ID:** `result`

**Result States:**

| State            | Description                        |
| ---------------- | ---------------------------------- |
| `SUCCESS`        | Verification passed                |
| `FAIL`           | Verification failed                |
| `PENDING`        | Verification pending manual review |
| `PARTIAL`        | Partial match - some checks passed |
| `UPLOAD_SUCCESS` | Document upload completed          |
| `UPLOAD_FAIL`    | Document upload failed             |
| `PROVIDER_ERROR` | Provider encountered an error      |

**Events:**

| Event                 | Description                                           |
| --------------------- | ----------------------------------------------------- |
| `form:result:ready`   | User pressed the CTA on the result screen             |
| `form:result:loaded`  | Result screen has been rendered                       |
| `form:result:failed`  | User pressed the CTA on a FAIL-state result screen    |
| `form:result:success` | User pressed the CTA on a SUCCESS-state result screen |
| `form:result:partial` | User pressed the CTA on a PARTIAL-state result screen |
| `form:result:pending` | User pressed the CTA on a PENDING-state result screen |

**Example:**

```javascript theme={null}
const resultSuccess = sdk.component('form', {
  name: 'RESULT',
  type: 'manual',
  state: 'SUCCESS',
  title: { label: 'Complete' },
  descriptions: [{ label: 'Process is now complete.' }],
  cta: { label: 'Done' }
});

resultSuccess.on('form:result:success', (payload) => {
  console.log('User dismissed the success screen');
});

await resultSuccess.mount('#form-container');
```

***

### Retry

Shown when verification returns a partial result and the user can retry. Allows re-entry of data that failed verification and intelligently adapts the retry flow based on the type of failure.

**Screen ID:** `retry`

**Events:**

| Event               | Description                   |
| ------------------- | ----------------------------- |
| `form:retry:loaded` | Retry screen mounted          |
| `form:retry:ready`  | User completed the retry form |
| `form:retry:failed` | Retry screen failed to load   |

**Example:**

```javascript theme={null}
const retry = sdk.component('form', {
  name: 'RETRY',
  type: 'manual'
});

retry.on('form:retry:loaded', (payload) => {
  console.log('Retry screen displayed - user can correct data');
});

await retry.mount('#form-container');
```

#### Smart Retry Behavior

The Retry screen intelligently adapts based on the type of verification failure. When verification returns a partial match, the SDK analyzes the failure type and presents the appropriate retry flow.

<AccordionGroup>
  <Accordion title="Previous Address Request">
    **Triggered when:** Verification returns a `partial` alert on personal details (e.g., address could not be confirmed against records).

    **What happens:** The Retry screen displays the personal details form with an additional toggle asking "Have you been at your current residential address for less than 6 months?" When the user enables this toggle, a previous address field appears prompting them to enter their prior residential address.

    **Purpose:** Helps resolve address verification failures by providing additional residential history that the verification provider can use to confirm the user's identity.
  </Accordion>

  <Accordion title="Additional ID Request">
    **Triggered when:** Primary ID verification fails with a `404` alert (e.g., the submitted document could not be verified against records).

    **What happens:** The Retry screen displays additional document types that have not been submitted yet, prompting the user to select and fill in an alternative form of ID. Documents already submitted are filtered out from the selection list.

    **Purpose:** Provides a fallback path when the initial document cannot be verified, allowing the user to supply a different identity document for verification.
  </Accordion>
</AccordionGroup>

**Retry Flow:**

1. Initial verification is submitted from the Review screen
2. Verification returns a partial result (via `partial` or `404` alert)
3. The SDK determines the failure type: personal details failure (`VERIFICATION_FAILED_IDS.NAME`) or document failure (`VERIFICATION_FAILED_IDS.ID`)
4. The Retry screen presents the appropriate fields based on the failure type
5. The user provides additional information (previous address or alternative ID)
6. The flow transitions to the Review screen for re-submission

**Example with retry limit:**

```javascript theme={null}
const retry = sdk.component('form', {
  name: 'RETRY',
  type: 'manual'
});

const resultFail = sdk.component('form', {
  name: 'RESULT',
  type: 'manual',
  state: 'FAIL',
  title: { label: 'Max attempts reached' },
  descriptions: [
    { label: 'You have reached the maximum number of attempts.' }
  ],
  cta: { label: 'Close' }
});

let retryCount = 0;

// Fires when user presses CTA on PARTIAL result screen
review.on('form:result:partial', async () => {
  if (retryCount < 2) {
    retry.mount('#form-container');
    retryCount += 1;
  } else {
    resultFail.mount('#form-container');
  }
});

retry.on('form:retry:loaded', (payload) => {
  console.log('Retry screen displayed - attempt', retryCount);
});
```

***

### Document Upload

Main document upload screen for uploading supporting documents.

**Screen ID:** `doc_upload`

**Events:**

| Event                      | Description                               |
| -------------------------- | ----------------------------------------- |
| `form:doc_upload:ready`    | User pressed the CTA on the upload screen |
| `form:doc_upload:loaded`   | Upload screen has been rendered           |
| `form:doc_upload:success`  | Document uploaded successfully            |
| `form:doc_upload:failed`   | Document upload failed                    |
| `form:doc_upload:navigate` | User navigated from upload screen         |

**Example:**

```javascript theme={null}
const docUpload = sdk.component('form', {
  name: 'DOC_UPLOAD',
  type: 'doc_upload'
});

docUpload.on('form:doc_upload:success', (payload) => {
  console.log('Document uploaded successfully');
});

docUpload.on('form:doc_upload:failed', (payload) => {
  console.log('Upload failed');
});

await docUpload.mount('#form-container');
```

***

### Required Document Upload

Displays documents that are required for verification and must be uploaded.

**Screen ID:** `required_document_upload`

**Events:**

| Event                                  | Description                                         |
| -------------------------------------- | --------------------------------------------------- |
| `form:required_document_upload:ready`  | User completed required uploads and pressed the CTA |
| `form:required_document_upload:loaded` | Required upload screen has been rendered            |
| `form:required_document_upload:failed` | Required upload screen failed to load               |

***

### Partial Document Upload

Displays a list of documents where a minimum number must be uploaded (e.g., "upload at least 2 of these 4 documents").

**Screen ID:** `partial_document_upload`

**Events:**

| Event                                 | Description                                        |
| ------------------------------------- | -------------------------------------------------- |
| `form:partial_document_upload:ready`  | User completed partial uploads and pressed the CTA |
| `form:partial_document_upload:loaded` | Partial upload screen has been rendered            |
| `form:partial_document_upload:failed` | Partial upload screen failed to load               |

***

### Optional Document Upload

Displays optional documents that users can upload to strengthen their verification.

**Screen ID:** `optional_document_upload`

**Events:**

| Event                                  | Description                                         |
| -------------------------------------- | --------------------------------------------------- |
| `form:optional_document_upload:ready`  | User completed optional uploads and pressed the CTA |
| `form:optional_document_upload:loaded` | Optional upload screen has been rendered            |
| `form:optional_document_upload:failed` | Optional upload screen failed to load               |

***

## Typical Screen Flow

### OCR Flow (with IDV)

```
[IDV Capture] → Review (type: 'ocr') → Result
```

The IDV flow handles document capture. The form module provides the Review screen to display extracted data for user confirmation.

### Manual Flow

```
Welcome → Consent → Personal Details → Document Selection → Review → Loading → Result → [Retry if failed]
```

### Document Upload Flow

```
Welcome → Consent → Required Uploads → Partial Uploads → Optional Uploads → Review → Result
```

***

## Screen-Level Event Listening Example

```javascript theme={null}
const sdk = await OneSdk({
  session: { token: 'your-token' },
  recipe: {
    form: {
      provider: {
        name: 'react',
        googleApiKey: 'your-google-api-key'
      }
    }
  }
});

const formComponent = sdk.component('form', {
  name: 'WELCOME',
  mode: 'individual',
  type: 'manual'
});

// Track every screen transition
const screens = [
  'welcome', 'start', 'consent', 'document',
  'personal', 'review', 'loading', 'result', 'retry',
  'doc_upload', 'required_document_upload',
  'partial_document_upload', 'optional_document_upload'
];

screens.forEach(screen => {
  formComponent.on(`form:${screen}:ready`, (payload) => {
    console.log(`[${screen}] ready`);
  });

  formComponent.on(`form:${screen}:loaded`, (payload) => {
    console.log(`[${screen}] loaded`);
  });

  formComponent.on(`form:${screen}:failed`, (payload) => {
    console.error(`[${screen}] failed`);
  });
});

// Handle verification outcomes
// Review-level result events (only with customResult: true in manual mode)
formComponent.on('form:review:success', () => {
  console.log('Verification passed — handle custom result UI');
});

// Result screen CTA events (fired when user presses CTA on result screens)
formComponent.on('form:result:success', () => {
  console.log('User pressed CTA on SUCCESS result screen');
});

formComponent.on('form:result:partial', () => {
  console.log('User pressed CTA on PARTIAL result screen');
});

formComponent.on('form:result:pending', () => {
  console.log('User pressed CTA on PENDING result screen');
});

await formComponent.mount('#form-container');
```

***

## Related

* [Form Module Overview](/docs/sdk-reference/form-module)
* [Form Configuration](/docs/sdk-reference/form-module/configuration)
* [Event System](/docs/sdk-reference/events)