Phone Input Component

1. Overview
2. Key Features
3. Configuration Properties
- Base Properties
- Component Specific Properties
4. Configuration Examples
5. API Reference

1. Overview

The PHONE_INPUT component provides a specialized input field for phone numbers with country code selection and validation.

🛝 Use the Dynamic Form Playground to see the Phone Input component in action and try out different configurations

2. Key Features

International phone number input with country code selection
Built-in phone number validation
Customizable area code and line number labels
Default country code configuration
Translation and string interpolation support
Custom error messaging

3. Configuration Properties

Base Properties

Property	Type	Required	Description
`type`	`'PHONE_INPUT'`	Yes	Specifies the field type as PHONE_INPUT.
`id`	`string`	Yes	Unique identifier for the field. The field's value is stored in the form state under this key.
`renderName`	`string`	No	Optional name added as `data-render-name` attribute to locate the rendered element in the DOM.
`label`	`string`	Yes	Label text displayed above the field. Supports translation and string interpolation.
`value`	`string`	No	The field's initial value including country code (e.g., `"+49123456789"`). If set, the field will be pre-filled with this value.
`hint`	`string`	No	Additional hint text displayed below the field.
`note`	`string`	No	Informational note displayed when there are no errors.
`infoIcon`	`DfInfoIconConfig`	No	Info icon with popover. Object with `popoverText` (string, required) and `popoverDirection` (`'top'`, `'bottom'`, `'left'`, `'right'`).
`validators`	`array`	No	Validation rules for the field. Common types: `REQUIRED`, `PATTERN`, `MIN_LENGTH`, `MAX_LENGTH`. The component has built-in phone number validation based on country. Each validator has `type` and optional `errorMessage`.
`testId`	`string`	No	Test identifier for automated testing. Set as `data-testid` attribute.
`acl`	`array`	No	Access control rules for field visibility/editability. Each rule has `state` (`'hidden'`, `'readonly'`, `'disabled'`, `'visible'`, `'editable'`) and optional `condition` (Filtrex expression).
`columnSpan`	`number`	No	Number of columns to span (1-12) in CUSTOM_COLUMN layout. Default: 12 (full width).
`spacing`	`string`	No	Margin spacing before next field: `'NONE'` (0px), `'XS'` (8px), `'S'` (16px), `'M'` (24px), `'L'` (32px), `'XL'` (48px), `'XXL'` (64px).

Component Specific Properties

Property	Type	Required	Description
`areaCodeLabel`	`string`	No	Set the text at the top of the dropdown and aria-label of area code field. The default value is 'Area Code'.
`countryCode`	`string`	No	The default country code for the phone input.
`errorMessage`	`string`	No	Custom error message for validation
`lineNumberLabel`	`string`	No	The aria-label of line number field.
`placeholder`	`string`	No	Placeholder to be displayed in the field when the input is empty. It's translatable by default and supports string interpolation.

4. Configuration Examples

Basic Phone Input

{
  "id": "phoneNumber",
  "type": "PHONE_INPUT",
  "label": "Phone Number",
  "placeholder": "Enter your phone number",
  "countryCode": "DE",
  "validators": [
    {
      "type": "REQUIRED",
      "errorMessage": "Phone number is required"
    }
  ]
}

Phone Input with Custom Labels

{
  "id": "contactNumber",
  "type": "PHONE_INPUT",
  "label": "Contact Number",
  "placeholder": "Enter phone number",
  "countryCode": "DE",
  "areaCodeLabel": "Country Code",
  "lineNumberLabel": "Phone Number",
  "validators": [
    {
      "type": "REQUIRED"
    }
  ]
}

Phone Input with Custom Error Message

{
  "id": "emergencyContact",
  "type": "PHONE_INPUT",
  "label": "Emergency Contact",
  "placeholder": "Enter phone number",
  "countryCode": "AT",
  "errorMessage": "Please provide a valid emergency contact number",
  "validators": [
    {
      "type": "REQUIRED"
    }
  ]
}

Phone Input with Custom Pattern Validation

{
  "id": "germanPhoneNumber",
  "type": "PHONE_INPUT",
  "label": "German Phone Number",
  "placeholder": "Enter German phone number",
  "countryCode": "DE",
  "validators": [
    {
      "type": "PATTERN",
      "pattern": "^\\+49[0-9]{10,11}$",
      "errorMessage": "Must be a German phone number starting with +49"
    },
    {
      "type": "REQUIRED",
      "errorMessage": "Phone number is required"
    }
  ]
}

Phone Input with Prefilled Value

{
  "id": "businessPhone",
  "type": "PHONE_INPUT",
  "label": "Business Phone",
  "placeholder": "Enter business phone",
  "value": "+49301234567",
  "countryCode": "DE",
  "validators": [
    {
      "type": "REQUIRED",
      "errorMessage": "Business phone is required"
    }
  ]
}

5. API Reference

For complete API documentation, see DfPhoneInputConfig.

For Aquila component documentation and design guidelines, see Phone Input - Aquila Design System.