Intl Phone Number Input

When implementing the InternationalPhoneNumberInput widget, follow these patterns for common tasks:

Form Integration

Integrate with a Flutter Form widget and use autoValidateMode (e.g., AutovalidateMode.onUserInteraction) to provide real-time feedback. Always handle the onInputChanged callback to receive the updated PhoneNumber object.

Form(
  key: _formKey,
  child: InternationalPhoneNumberInput(
    onInputChanged: (PhoneNumber number) {
      // Handle phone number changes
    },
    validator: (String? value) {
      // Custom validation logic
      return null;
    },
    autoValidateMode: AutovalidateMode.onUserInteraction,
  ),
),

Programmatic Control with Controllers

Use a TextEditingController via the textFieldController property to control the text input programmatically.

final TextEditingController _controller = TextEditingController();

InternationalPhoneNumberInput(
  textFieldController: _controller,
  onInputChanged: (PhoneNumber number) {
    // number contains the complete phone number data
  },
)

Customizing the Selector and Input Decoration

Use selectorConfig to change the selector type (e.g., PhoneInputSelectorType.BOTTOM_SHEET) and appearance, and inputDecoration for standard Material Design styling.

InternationalPhoneNumberInput(
  selectorConfig: SelectorConfig(
    selectorType: PhoneInputSelectorType.BOTTOM_SHEET,
    backgroundColor: Colors.blue,
    showFlags: true,
  ),
  inputDecoration: InputDecoration(
    labelText: 'Phone Number',
    border: OutlineInputBorder(),
  ),
)

The library uses a standardized data model for country information. Each country entry in the list contains geographic codes, dialing information, and localized names. This data is used to populate country selectors and validate phone numbers.

Each country object includes:

• alpha_2_code: The 2-letter ISO country code (e.g., VE, VN, ZM).
• alpha_3_code: The 3-letter ISO country code (e.g., VEN, VNM, ZMB).
• num_code: The numeric ISO country code.
• en_short_name: The name of the country in English.
• nationality: The corresponding nationality string.
• dial_code: The international dialing prefix (e.g., +58, +84).
• nameTranslations: A map of language codes to the country's name in that language (e.g., ja for Japanese, zh for Chinese).

{
  "num_code": "862",
  "alpha_2_code": "VE",
  "alpha_3_code": "VEN",
  "en_short_name": "Venezuela (Bolivarian Republic of)",
  "nationality": "Venezuelan",
  "dial_code": "+58",
  "nameTranslations": {
    "sk": "Venezuela",
    "en": "Venezuela",
    "ja": "ベネズエラ"
  }
}

The countryList provides a collection of maps representing countries available for the phone input. Each country entry contains geographic codes, names, and translations. This data is used to populate country selectors and provide localized names.

Each country map contains the following keys:

• num_code: The numeric country code (as a string).
• alpha_2_code: The ISO 3166-1 alpha-2 country code (e.g., AF, AX, AL).
• alpha_3_code: The ISO 3166-1 alpha-3 country code (e.g., AFG, ALA, ALB).
• en_short_name: The English short name of the country.
• nationality: The demonym or nationality associated with the country.
• dial_code: The international calling code (e.g., +93, +358).
• nameTranslations: A map of language codes to the country's name in that language (e.g., ja for Japanese, zh for Chinese).

{
  "num_code": "4",
  "alpha_2_code": "AF",
  "alpha_3_code": "AFG",
  "en_short_name": "Afghanistan",
  "nationality": "Afghan",
  "dial_code": "+93",
  "nameTranslations": {
    "ja": "アフガニスタン",
    "en": "Afghanistan"
  }
}

The InternationalPhoneNumberInput widget provides a customizable text field for international phone numbers with an integrated country selector. It supports real-time formatting, validation using Google's libphonenumber, and multiple selector display modes (dropdown, bottom sheet, or dialog).

Key features include:

• Formatting as you type.
• Country selection with flags.
• Real-time validation via onInputValidated.
• Form integration with validator and onSaved callbacks.
• Country filtering via ISO codes.

InternationalPhoneNumberInput(
  onInputChanged: (PhoneNumber number) {
    print(number.phoneNumber);
  },
  onInputValidated: (bool value) {
    print('Is valid: $value');
  },
  selectorConfig: SelectorConfig(
    selectorType: PhoneInputSelectorType.BOTTOM_SHEET,
  ),
  ignoreBlank: false,
  autoValidateMode: AutovalidateMode.disabled,
  selectorTextStyle: TextStyle(color: Colors.black),
  initialValue: PhoneNumber(isoCode: 'NG'),
  textFieldController: myController,
  formatInput: false,
  keyboardType: TextInputType.numberWithOptions(signed: true, decimal: true),
  inputBorder: OutlineInputBorder(),
  onSaved: (PhoneNumber number) {
    print('On Saved: $number');
  },
)