Phone Field

The phone field is for phone numbers with automatic validation, cleaning, and formatting using libphonenumber-js. It validates phone numbers against specific countries and can format them in international or national format.

When to Use

Use phone when you need:

Phone number validation for specific countries
Automatic cleaning of malformed phone numbers
Consistent formatting (international vs national)
SmartFix suggestions for invalid phone numbers

Basic Usage

{
  type: 'phone',
  label: 'Phone number',
  key: 'phoneNumber',
  order: 0,
  countries: ['AU']
}

This automatically:

Validates phone numbers are valid for Australia
Cleans and formats phone numbers on load and cell changes
Formats in national format (e.g., 0413 900 967)
Provides smartFix suggestions for invalid numbers

Properties

Required

countries (CountryCode[]) - Array of country codes to validate against (e.g., ['AU', 'US', 'GB']). Phone number must be valid for at least one of these countries.

Optional

withInternationalCode (boolean) - Controls validation and output format:
- true: Requires + prefix in input, outputs international format (+61 413 900 967)
- false: Accepts both formats, outputs national format (0413 900 967)
- Default: false

Auto-Clean Options

Controls automatic data transformation on load and cell changes:

autoClean (false | object) - Controls automatic phone number cleaning. Default: enabled with defaults below
- Set to false to disable auto-cleaning (only smartFix suggestions will be available)
- Set to object to customize cleaning behavior

When autoClean is enabled (default), you can configure:

autoClean.countries (CountryCode[]) - Override countries for transformation. Default: uses field-level countries
autoClean.withInternationalCode (boolean) - Override format for transformation. Default: uses field-level withInternationalCode

Note: SmartFix suggestions always use these same options, even if autoClean: false.

Other

defaultValue (string) - Default phone number value

Plus all common field properties.

Automatic Behavior

The SDK automatically:

Adds a phone validator (if not present) with autoFixOptions for smartFix suggestions
Adds a FormatPhoneNumbers transformer (unless autoClean: false) that runs on load and cell changes
Validates and formats phone numbers using libphonenumber-js

Examples

Basic Australian Phone

{
  type: 'phone',
  label: 'Phone number',
  key: 'phoneNumber',
  order: 0,
  countries: ['AU']
}

Behavior:

Input: "0413 900 967" → Valid ✓ → Stored: "0413 900 967"
Input: "+61 413 900 967" → Valid ✓ → Stored: "0413 900 967" (converted to national)
Input: "++61 413 900 967" → Valid ✓ → Stored: "0413 900 967" (cleaned)
Input: "+1 202 555 0123" → Invalid ✗ (US number, not AU)

International Format

{
  type: 'phone',
  label: 'Phone number',
  key: 'phoneNumber',
  order: 0,
  countries: ['AU'],
  withInternationalCode: true
}

Behavior:

Input: "0413 900 967" → Valid ✓ → Stored: "+61 413 900 967" (converted to international)
Input: "+61 413 900 967" → Valid ✓ → Stored: "+61 413 900 967"
Input: "0413900967" → Valid ✓ → Stored: "+61 413 900 967" (cleaned and formatted)

Multiple Countries

{
  type: 'phone',
  label: 'Phone number',
  key: 'phoneNumber',
  order: 0,
  countries: ['AU', 'US', 'GB']
}

Behavior:

Input: "0413 900 967" → Valid ✓ (Australian)
Input: "+1 202 555 0123" → Valid ✓ (US)
Input: "020 7946 0958" → Valid ✓ (UK)
Input: "+33 1 42 86 82 00" → Invalid ✗ (French, not in allowed countries)

Disable Auto-Clean (Strict Mode)

{
  type: 'phone',
  label: 'Phone number',
  key: 'phoneNumber',
  order: 0,
  countries: ['AU'],
  autoClean: false
}

Behavior:

Input: "0413 900 967" → Valid ✓ → Stored: "0413 900 967" (no cleaning)
Input: "++61 413 900 967" → Valid ✓ → Stored: "++61 413 900 967" (no cleaning, but still valid)
Input: "0413900967" → Valid ✓ → Stored: "0413900967" (no formatting applied)
SmartFix suggestions still available for invalid numbers

Custom Auto-Clean Options

{
  type: 'phone',
  label: 'Phone number',
  key: 'phoneNumber',
  order: 0,
  countries: ['AU', 'US'],
  autoClean: {
    countries: ['AU'], // Only clean Australian numbers
    withInternationalCode: true // Always output international format
  }
}

Behavior:

Input: "0413 900 967" → Stored: "+61 413 900 967" (cleaned as AU, international format)
Input: "+1 202 555 0123" → Stored: "+1 202 555 0123" (valid US, but not cleaned)
Validator still accepts both AU and US numbers
Transformer only cleans AU numbers

With Additional Validators

{
  type: 'phone',
  label: 'Phone number',
  key: 'phoneNumber',
  order: 0,
  countries: ['AU'],
  validators: [
    { type: 'required', message: 'Phone number is required' }
  ]
}

Behavior:

Empty input → Invalid ✗ (required)
Input: "0413 900 967" → Valid ✓
Phone validator is automatically added alongside required validator

How Phone Validation Works

The phone field uses libphonenumber-js for validation and formatting.

Validation Process

Trim and clean - Removes whitespace and cleans formatting characters
Parse - Attempts to parse the phone number
Validate - Checks if the number is valid for one of the allowed countries
Format - Formats the number according to withInternationalCode setting

What Gets Accepted

The validator is lenient and accepts phone numbers with various formatting:

✅ Accepted formats:

"0413 900 967" - Spaces
"0413-900-967" - Hyphens
"(02) 5550 4321" - Parentheses
"+61 413 900 967" - International format
"0413900967" - No formatting
"+61 1800 - 160 - 401" - Excessive spaces and mixed separators (cleaned by libphonenumber)
"02 5550 4321 b" - Letters (stripped by libphonenumber)

❌ Rejected formats:

"123" - Too short
"+999 123 456 789" - Invalid country code
"+1 202 555 0123" - Valid US number but not in countries: ['AU']

Why Is Validation Lenient?

libphonenumber-js is designed to parse phone numbers, not strictly validate input format. It:

Strips non-digit characters (except +)
Handles various formatting styles
Focuses on whether the digits form a valid phone number

This means:

"+61 1800 - 160 - 401" is considered valid because it can be parsed to a valid Australian phone number
"02 5550 4321 b" is considered valid because the 'b' is stripped and the remaining digits are valid

If you need strict format validation, consider:

Using autoClean: false to see the raw input
Adding custom validators for format requirements
Educating users that malformed numbers will be auto-corrected

The transformer (when autoClean is enabled) will clean these numbers to proper format, so users see the corrected version.

Phone Number Formatting

Different phone number types are formatted differently according to each country's standards:

Australian Examples

Mobile: 0413 900 967 (spaces, no parentheses)
Landline: (02) 5550 4321 (parentheses for area code)
Toll-free: 1800 160 401 (spaces, no parentheses)

International Format

When withInternationalCode: true:

Australian mobile: +61 413 900 967
US number: +1 202 555 0123
UK number: +44 20 7946 0958

National Format

When withInternationalCode: false (default):

Australian mobile: 0413 900 967
US number: (202) 555-0123
UK number: 020 7946 0958

Note: Formatting variations (parentheses vs spaces) are determined by libphonenumber-js based on the phone number type and country standards, not by our configuration.

Transform vs Validation

Validation checks if the phone number is valid:

{
  countries: ['AU'],
  withInternationalCode: false
}

Accepts: "0413 900 967", "+61 413 900 967", "0413900967"
Rejects: "+1 202 555 0123" (US number)

Transformation (autoClean) formats the phone number:

{
  countries: ['AU'],
  autoClean: {
    withInternationalCode: true
  }
}

Input: "0413 900 967" → Stored: "+61 413 900 967"
Input: "+61413900967" → Stored: "+61 413 900 967"
Input: "++61 413 900 967" → Stored: "+61 413 900 967"

Equivalent Manual Configuration

This phone field:

{
  type: 'phone',
  countries: ['AU'],
  withInternationalCode: false
}

Is equivalent to:

{
  type: 'text',
  validators: [
    {
      type: 'phone',
      countries: ['AU'],
      withInternationalCode: false,
      autoFixOptions: {
        countries: ['AU'],
        withInternationalCode: false
      }
    }
  ],
  transformers: [
    {
      action: 'formatPhoneNumbers',
      payload: {
        runOns: ['load', 'cells-change'],
        countries: ['AU'],
        withInternationalCode: false
      }
    }
  ]
}

The phone field type automatically adds the validator and transformer with matching options.

Country Codes

Use ISO 3166-1 alpha-2 country codes:

Code	Country
`AU`	Australia
`US`	United States
`GB`	United Kingdom
`CA`	Canada
`NZ`	New Zealand
`DE`	Germany
`FR`	France
`JP`	Japan
`CN`	China

See libphonenumber-js supported countries for the full list.

Common Patterns

International Business

{
  type: 'phone',
  label: 'Contact number',
  key: 'contactNumber',
  order: 0,
  countries: ['AU', 'US', 'GB', 'CA', 'NZ'],
  withInternationalCode: true
}

Single Country (Strict)

{
  type: 'phone',
  label: 'Australian mobile',
  key: 'mobile',
  order: 0,
  countries: ['AU'],
  validators: [
    { type: 'required' }
  ]
}

Optional Phone with Cleaning

{
  type: 'phone',
  label: 'Phone number (optional)',
  key: 'phoneNumber',
  order: 0,
  countries: ['AU']
  // No required validator, so empty is allowed
}

Strict Format (No Auto-Clean)

{
  type: 'phone',
  label: 'Phone number',
  key: 'phoneNumber',
  order: 0,
  countries: ['AU'],
  autoClean: false,
  validators: [
    {
      type: 'required',
      message: 'Phone number is required'
    }
  ]
}

Phone Field

On this page