Personal

Quick Start

Add HTML Container

<div id="form"></div>

Initialize Component

const personal = oneSdk.component("form", {
  name: "PERSONAL",
  type: "manual",
});

// Mount to your container
personal.mount("#form");

Configuration Guide

Basic Configuration

General Settings

const personal = oneSdk.component('form', {
  name: "PERSONAL",
  type: "manual",
  title: {
    label: "Your Personal Details",
    style: { 'ff-title': {} }
  },
  descriptions: [
    {label: 'We need to collect your data'}
  ],
  logo: {
    src: './assets/logo.png' // path to your logo
  },
  style: {
    'ff-logo': {
      'width': '50px'
    }
  }
});

For more detailed configuration options, please refer to the Field Configuration section below

Country-Specific Configuration

You can customize fields based on country (using ISO 3166-1 alpha-3 codes) and state:

const personal = oneSdk.component('form', {
  name: "PERSONAL",
  type: "manual",
  personal: {
    countries: {
      AUS: {
        NSW: { /* NSW specific config */ },
        default: { /* Other AU states */ }
      },
      NZL: {
        default: { /* NZ config */ }
      },
      default: {
        default: { /* Default config */ }
      }
    }
  }
});

Field Configuration

Name
Date of Birth
Address
Custom

Name

Available Fields

givenName
middleName
familyName

Common Properties

fieldType: ‘input’
dataType: ‘text’
label: Custom label
hide: true/false
rules:
- required: { value: ‘boolean’, message: ‘string’ }
- pattern: { value: ‘regex string’, message: ‘string’ }

fields: [
  {
    fieldType: "input",
    name: "givenName",
    label: "Given Name:",
    dataType: 'text',
    hide: false,
    helperText: "As shown on your ID",
    rules: {
      required: {
        value: true,
        message: "Please enter your given name"
      },
      pattern: {
        value: "^[a-zA-Z]+(\\s+[a-zA-Z]+)*$",
        message: "Please use alphabetic characters only"
      }
    }
  }
]

Date of Birth

Calendar Types

gregorian
buddhist
chinese
islamic
persian

Locales

en (English)
zh (Chinese)
ja (Japanese)
ko (Korean)

{
  fieldType: "date",
  name: "dateOfBirth",
  label: "Date of Birth",
  calendarConfig: {
    type: 'gregorian',
    locale: 'en',
    age: {
      min: 18,
      max: 85,
      message: "Age must be between 18 and 85"
    }
  }
}

Address

To enable address auto-complete, you must provide a Google Maps API key during SDK initialization.

As of March 1st, 2025, google deprecate AutocompleteService to new customers and replace it with AutocompleteSuggestion source . To enable new AutocompleteSuggestion by google, you can set useGoogleAutoCompleteSuggestion to true.

const oneSdk = await OneSdk({
  session: sessionObjectFromBackend,
  mode: "production",
  recipe: {
    form: {
      provider: {
        name: 'react',
        googleApiKey: "YOUR_API_KEY",

        // Optional. Default: false
        // This is to opt-in the new `AutocompleteSuggestion` by google
        useGoogleAutoCompleteSuggestion: true
      }
    }
  }
});

Available Fields

address.fullAddress
address.country
address.unitNumber
address.streetAddress
address.town
address.state
address.postalCode

Common Properties

fieldType: ‘input’ | ‘select’ | ‘text’
name: ‘field name’ (see Available Fields)
dataType: ‘text’
label: Custom label
hide: true/false
rules:
- required: { value: ‘boolean’, message: ‘string’ }
- pattern: { value: ‘regex string’, message: ‘string’ }

{
  // Main address field configuration
  fieldType: 'address',
  dataType: 'current_addr',
  name: 'address.fullAddress',
  // Restrict address lookup to Australia and New Zealand only
  acceptedCountries: ["AUS", "NZL"],

  // Configuration for manual address entry fields
  manualFieldConfig: [
    {
      // Country dropdown field
      fieldType: 'select',
      dataType: 'text',
      hide: false,
      label: 'Country',
      name: 'address.country',
      rules: {
        required: {
          value: true,
          message: `Please select your country`,
        },
      },
    },
    {
      // Optional unit/apartment number field
      fieldType: 'input',
      dataType: 'text',
      hide: false,
      label: 'Unit Number (optional)',
      name: 'address.unitNumber',
    },
    {
      // Street address field with required validation
      fieldType: 'input',
      dataType: 'text',
      hide: false,
      label: 'Street Address',
      name: 'address.streetAddress',
      rules: {
        required: {
          value: true,
          message: 'Please enter your street address',
        },
      },
    },
    {
      // Suburb/Town field with required validation
      fieldType: 'input',
      dataType: 'text',
      hide: false,
      label: 'Suburb / Town',
      name: 'address.town',
      rules: {
        required: {
          value: true,
          message: 'Please enter your suburb/town.',
        },
      },
    },
    {
      // State dropdown field with required validation
      fieldType: 'select',
      dataType: 'text',
      hide: false,
      label: "State",
      name: 'address.state',
      placeholder: 'Select Your State',
      rules: {
        required: {
          value: true,
          message: 'Please enter your state',
        },
      },
    },
    {
      // Postal code field with length and required validation
      dataType: 'text',
      hide: false,
      label: "Postal Code",
      name: 'address.postalCode',
      rules: {
        required: {
          value: true,
          message: 'Please enter your postal code',
        },
        minLength: {
          value: 4,
          message: "should be 4 characters",
        },
        maxLength: {
          value: 4,
          message: "Should be 4 characters",
        },
      },
    },
  ],
}

Caution

When customizing the manualFieldConfig field, you must override all fields in manualFieldConfig as shown in the example above. Additionally, if you have specified acceptedCountries, you will need to redefine the configuration for each country in the personal field. Currently, this is the only available approach.

Best Practice

Create reusable units to define the manualFieldConfig for each supported country. This is useful when you need different validation rules for different countries (e.g., postal code lengths vary between Australia and the UK).

Custom

Other than the default fields, you can also add custom fields to the form and manage the order of the fields.

Properties

name: ‘extraData.yourDesiredFieldName’
fieldType: ‘input’
dataType: ‘text’
label: Custom label
hide: true/false
rules:
- required: { value: ‘boolean’, message: ‘string’ }
- pattern: { value: ‘regex string’, message: ‘string’ }

You must define the fields to all your supported countries and ensure the field name has prefix extraData. followed by the field name

Add new fields
Fields Ordering

In this example, the field will be appear at the top of the default form.

{
  countries: {
    default: {
      default: {
        fields: [
          {
            name: "extraData.personTitle",
            fieldType: "input",
            dataType: "text",
            label: "Title",
            rules: {
              required: {
                value: true,
                message: "Please enter your title",
              },
            },
          },
        ],
      },
    },
  },
}

If you want to change the order of the fields, simply add them to the fields array in the desired order. For example, if you want a field to appear below the givenName field, redefine the existing givenName field and add the new field below it in the array.

{
  countries: {
    default: {
      default: {
        fields: [
          {
            name: "givenName",
          },
          {
            name: "extraData.personTitle",
            fieldType: "input",
            dataType: "text",
            label: "Title",
            rules: {
              required: {
                value: true,
                message: "Please enter your title",
              },
            },
          },
        ],
      },
    },
  },
}

Event Handling

form:personal:loaded

Emitted when the screen is successfully mounted

form:personal:ready

Emitted when form submission is complete and ready for next step

form:personal:failed

Emitted when an error occurs during form operation

Event Listener Example

personal.on("form:personal:ready", (data) => {
  // Handle successful form completion
  console.log("Form completed:", data);
});

Best Practice

Always implement error handling and loading states when working with Personal Screen events to provide a smooth user experience.

OneSDK

Smart UI (for deprecation)

Quick Start

Configuration Guide

General Settings

Field Configuration

Name

Available Fields

Common Properties

Date of Birth

Calendar Types

Locales

Address

Available Fields

Common Properties

Caution

Best Practice

Custom

Properties

Event Handling

form:personal:loaded

form:personal:ready

form:personal:failed

Event Listener Example

Best Practice

​Quick Start

​Configuration Guide

​General Settings

​Field Configuration

​Name

Available Fields

Common Properties

​Date of Birth

Calendar Types

Locales

​Address

Available Fields

Common Properties

Caution

Best Practice

​Custom

Properties

​Event Handling

form:personal:loaded

form:personal:ready

form:personal:failed

​Event Listener Example

Best Practice

Quick Start

Configuration Guide

General Settings

Field Configuration

Name

Date of Birth

Address

Custom

Event Handling

Event Listener Example