Skip to main content

​
Overview

The Form module’s React provider supports extensive customization of each screen’s content, styling, and behavior. Configuration is passed as module options when creating the form component.

​
ReactFormConfig

The main configuration type for the React form provider:
Additional page-level properties from TPageConfig can be included to customize individual screens.

​
Configuration Types

The type option determines the overall verification flow and primarily affects the Document Selection, Personal Details, Review, and Retry screens. Static screens (Welcome, Consent, Start) and progress screens (Loading, Result) are not affected by type. Doc upload screens are only shown when type is 'doc_upload'.

​
OCR Type

Used to display and review data that was automatically extracted by the IDV or OCR modules. In a typical OCR flow, the IDV flow handles document capture, and the form module is used to present the extracted data on the Review screen for user confirmation. Screens affected:
  • Review - Displays OCR-extracted data for user review and submission
  • Document Selection - Shows document type selection. Useful for specifying document type before mounting the OCR module. Unlike manual mode, OCR mode does not show manual input fields after selection.

​
Manual Type

For manual data entry flows. Users select their document type and manually enter their details. Screens affected:
  • Document Selection - Shows numberOfIDs and document options with cta button. After selection, displays manual input fields for the selected document.
  • Personal Details - Shown for manual data entry with country-specific field configurations
  • Review - Displays manually entered data with verify, hiddenForms, and readOnlyForms options
  • Retry - Allows re-entry of data that failed verification

​
Doc Upload Type

For supporting document file upload flows. Requires document upload configuration in the recipe. Screens affected:
  • Required/Partial/Optional Document Upload - These screens are only shown in this type
  • Review - Displays document upload summary
  • Personal Details - Not shown

​
Page Configuration Types

The Form module uses four page configuration types depending on the screen:

​
IStaticPageConfig

Used by: Welcome, Consent, Start, Document Upload screens

​
IIdCardPageConfig

Used by: Document Selection (manual, ocr, and doc_upload modes), Retry screens
OCR mode vs Manual mode: In OCR mode, Document Selection shows only the document type picker, useful for specifying the document type before mounting the OCR module. In manual mode, Document Selection shows the document type picker followed by manual input fields for the selected document.

​
IProgressPageConfig

Used by: Loading, Result screens

​
IFormPageConfig

Used by: Review, Personal Details, Retry screens

​
Multi-Document Review

When more than one document was scanned during the OCR/IDV capture flow (for example, a passport and a driver’s licence submitted for the same applicant), the Review screen renders one review section per scanned document instead of a single combined section. If only one document was scanned, the Review screen falls back to the original single-section behavior.
  • Section heading — each section’s heading is controlled by documentSourceLabel on the matching entry in documents (matched by type). If not set, built-in default labels are used for PASSPORT ('From your passport') and DRIVERS_LICENCE ("From your driver's licence"); other document types have no default label unless you set one.
  • Section order — sections are ordered with the primary document first. The primary document is determined by the individual’s extraData.idv_primary_document value (set during the IDV flow), matched against each scanned document’s type. Ordering is a no-op when only one document was scanned or when idv_primary_document is not set.

​
Content Customization

​
Content Object

Most text elements use the Content type for customization:

​
IBasicInfo

Base configuration shared by all static and card-based screens:

​
ActionContent

Used for buttons and call-to-action elements:

​
ListInfo

Used for instruction lists on static screens:
An array of Content objects. Each item represents an instruction or list entry, rendered with the ff-instruction-item and ff-instruction-icon CSS classes.

​
IDocuments

Configures a document type available for selection on the Document Selection screen, with optional country and state-specific field overrides.

​
CSS Styling

The Form module provides CSS class keys for styling customization through the style property on configuration objects.

​
CSS Class Keys

Example:

​
Form Fields

Form-based screens (Review, Personal Details, Retry) use configurable form fields.

​
Field Types

​
FormField Type

​
Field-Type-Specific Properties

In addition to the common FormField properties above, each fieldType supports its own specific properties.

​
input / number / textarea / hidden

​
date

Date fields support a calendarConfig property that controls the calendar system, locale, and age validation. calendarConfig properties:

​
select / multiselect

Matching and auto-select behavior when autocomplete: true:
  • Matching — as the user types, options are filtered to those whose label or value starts with the typed text (case-insensitive). Matching against value lets you use short codes as options (e.g. state codes like NSW) so users can filter by typing the code even though the displayed label is the full name (e.g. “New South Wales”).
  • Select on blur — when the field loses focus, if the typed text is an exact match (case-insensitive) to an option’s value, that option is automatically selected and the input is updated to show its label. Partial/prefix matches are not auto-selected on blur — only an exact value match triggers this.

​
address

Hidden streetNumber/streetName fields and auto-hide of streetAddressThe default manualFieldConfig for the address field type includes two additional fields, hidden by default, alongside the single free-text streetAddress field: address.streetNumber (label “Street Number”) and address.streetName (label “Street Name”). They let you split the street line into two inputs instead of one.If you override manualFieldConfig and set hide: false on either address.streetNumber or address.streetName, the address.streetAddress field is automatically force-hidden — you don’t need to hide it yourself, and the three fields are not intended to be shown together.

​
phone

​
checkbox / radio

​
contact-number

​
label

The label fieldType renders static display text. It has no additional field-type-specific properties beyond the common FormField properties.

​
Field Data Types

​
Validation Rules

Fields support validation through the rules property:

​
Default Screen Configurations

The form module provides built-in default configurations for each screen. When you pass custom configuration, your values are merged with the defaults — you only need to specify the properties you want to override. Properties not included in your configuration retain their defaults.
Configuration overrides are shallow-merged at each level. If you override a specific country or state key (e.g., AUS.NSW), only that key is replaced — all other country/state keys remain with their defaults. This means overriding just one country/state will leave all others using the built-in default configuration, which may produce unexpected behavior if the defaults don’t match your requirements. To ensure consistency, override all country/state keys you intend to support.

​
Welcome

​
Start

​
Document Selection (Manual)

​
Personal Details

When customizing the address manualFieldConfig, you must override all fields in manualFieldConfig, not just individual ones. This is because the manualFieldConfig array is replaced entirely, not merged field-by-field. Additionally, if you have specified acceptedCountries on the address field, you will need to define the configuration for each country in the personal.countries property.

​
Review

​
Loading

The Loading screen has different defaults per mode:

​
Result

The Result screen defaults vary by state. The initial state is PENDING.
Unlike SUCCESS/FAIL/PARTIAL/PROVIDER_ERROR, the TIMEOUT state has no creditHeaderIssueTitle/creditHeaderIssueDescriptions — it isn’t a credit-check-related outcome. The Result screen’s state must be set explicitly (e.g. by the host application) when a verification attempt has timed out; the form module does not have built-in polling-timeout logic that sets this state automatically.

​
Retry

The Retry screen extends the Review config with the Personal Details fields and Document Selection documents. It adds a previous address toggle field.

​
Doc Upload

​
Required Document Upload

​
Partial Document Upload

​
Optional Document Upload

​
Custom Fields

You can add custom fields to the Personal Details and Review screens. Custom field values are stored in the extraData object of the individual entity.

​
Naming Convention

Custom field names must use the extraData.idv. prefix followed by your desired field name:
For example, a field named extraData.idv.personTitle will store its value under the key idv.personTitle in the individual’s extraData object.

​
Adding a Custom Field

To add a custom field, include it in the fields array of your country configuration. When you only provide custom fields (without redefining existing fields), they appear at the top of the form, before the default fields.
You must define custom fields for all your supported countries. Configuration overrides are merged, so if you only define a custom field under one country (e.g., AUS), other countries will use the built-in default without your custom field — producing inconsistent forms. If you use country-specific configurations (e.g., AUS, NZL), each country entry must include the custom field.

​
Field Ordering

To control the order of fields on the Personal Details screen, redefine the fields array with entries in the desired order. Each entry needs at least the name property to reference an existing default field.

​
How It Works

  • Fields appear in the order they are listed in the fields array
  • To reference an existing default field, include an entry with just { name: 'fieldName' } — the default properties are preserved
  • To add a custom field at a specific position, insert it at the desired index in the array
  • Fields from the default configuration that are not included in your array will appear after your defined fields

​
Reordering Default Fields

For example, if the default order is givenName, middleName, familyName and you want familyName first:

​
Inserting a Custom Field at a Specific Position

To insert a custom field after givenName, redefine givenName (with just name) and place the custom field right after it:
This places Title directly after Given Name, with all remaining default fields (middleName, familyName, dateOfBirth, address) following after.

​
Document Upload Configuration

Document upload is configured through the recipe’s docUpload property:

​
DocUploadRecipeOptions

​
Partial Documents

​
Document Upload Validation

File uploads support validation rules:

​
Screen Configuration Examples

​
Customizing the Welcome Screen

​
Customizing the Result Screen

​
Country-Specific Field Configuration

In manual mode, form fields can be configured per country and state using the CountryConfig type. This is used in two places:
  • Document Selection screen — inside each entry of the documents array, via the countries property
  • Personal Details screen — via the personal.countries property
Use 'default' as a fallback key when no specific country or state match is found.

​
Document-Type-Specific Configuration

On the Document Selection screen, the countries configuration is nested within each document type in the documents array. This means the full configuration hierarchy has three levels:
  1. Document type — e.g., DRIVERS_LICENCE, PASSPORT, NATIONAL_HEALTH_ID
  2. Country — e.g., AUS, NZL, default
  3. State — e.g., NSW, VIC, default
Each document type carries its own independent CountryConfig, so different document types can require entirely different fields for the same country. For example, a driver’s licence in Australia requires a licence number and card number, while a passport for the same country requires a passport number and expiry date.
The Personal Details screen does not have the document-type level — it uses CountryConfig directly under personal.countries. Document Selection example: Configures country and state-specific fields for each document type. When a user selects a country (e.g., Australia) and state (e.g., NSW), the matching field configuration is used. The 'default' key acts as a fallback.
Personal Details example: Configures country-specific personal detail fields. Different countries can require different fields or validation rules.
The lookup order is:
  1. Exact country + exact state match (e.g., AUS → NSW)
  2. Exact country + default state (e.g., AUS → default)
  3. default country + default state