1. Install the latest component version

Check the OutSystems Forge for the International Phone Input component and ensure that the latest version is installed in your environment.

2. Manage your dependencies

Add a desired dependency in your application or library from the International Phone Input through manage dependencies and choose the elements that suits for your use-case:

3. Using the International Phone Input Block

Drag the International Phone Input lock and set it to the desired input widget.

The following options are available:

• WidgetId [Text]: The identifier of the widget containing the phone number.
• allowDropdown [Boolean]: Whether or not to allow the dropdown. If disabled, there is no dropdown arrow, and the selected flag is not clickable. Also we display the selected flag on the right instead because it is just a marker of state.
• autoHideDialCode [Boolean]: If there is just a dial code in the input: remove it on blur or submit. This is to prevent just a dial code getting submitted with the form. Requires nationalMode to be set to false.
• customContainer [Text]: Additional classes to add to the parent div.
• initialCountry [Text]: Set the initial country selection by specifying its country code. If you leave initialCountry blank, it will default to the first country in the list.
• nationalMode [Boolean]: Allow users to enter national numbers (and not have to think about international dial codes). Formatting, validation and placeholders still work. Then you can use getNumber to extract a full international number. This option now defaults to true, and it is recommended that you leave it that way as it provides a better experience for the user.
• preferredCountries [Text]: Specify the countries to appear at the top of the list. Any options that take country codes should be ISO 3166-1 alpha-2 codes.
• excludeCountries [Text]: In the dropdown, display all countries except the ones you specify here. Ex.: "us,gb".
• onlyCountries [Text]: In the dropdown, display only the countries you specify. Ex.: "pt,es,gb".
• formatOnDisplay [Boolean]: Format the input value (according to the nationalMode option) during initialisation, and on setNumber. Requires the utilsScript option.
• customDropdownContainerClass [Text]: Set the parent of the countries dropdown class. If empty will set the default. In mobile will be the HTML body.

4. Using the public Client actions

The following Client actions are available to be consumed:

• getExtension: Get the extension from the current number. Returns a string e.g. if the input value was "(702) 555-5555 ext. 1234", this would return "1234".
  • WidgetId [Input Text]: The identifier of the Widget containing the phone number.
  • PhoneNumberExtension [Output Text]: The phone number extension.
• getNumber: Get the current number in the given format (defaults to E.164 standard). Note that even if nationalMode is enabled, this can still return a full international number. Also note that this method expects a valid number, and so should only be used after validation.
  • WidgetId [Input Text]: The identifier of the Widget containing the phone number.
  • PhoneNumber [Output Text]: The phone number.
• getNumberType: Get the type (fixed-line/mobile/toll-free etc) of the current number.
  • WidgetId [Input Text]: The identifier of the Widget containing the phone number.
  • NumberTypeId [Output NumberType identifier]: The type of phone number.
• getSelectedCountryData: Get the country data for the currently selected flag.
  • WidgetId [Input Text]: The identifier of the Widget containing the phone number.
  • CountryData [Output CountryData]: The phone number Country data.
• getValidationError: Get more information about a validation error.
  • WidgetId [Input Text]: The identifier of the Widget containing the phone number.
  • ValidationErrorId [Output ValidationError identifier]: The phone number validation error.
• isValidNumber: Validate the current number. Expects an internationally formatted number (unless nationalMode is enabled). If validation fails, you can use getValidationError to get more information. Also see getNumberType if you want to make sure the user enters a certain type of number e.g. a mobile number.
  • WidgetId [Input Text]: The identifier of the Widget containing the phone number.
  • IsValid [Output Boolean]: If set to True means that the phone number is valid.
• setCountry: Change the country selection (e.g. when the user is entering their address)..
  • WidgetId [Input Text]: The identifier of the Widget containing the phone number.
  • CountryCode [Input Text]: Any options that take country codes should be ISO 3166-1 alpha-2 codes.
• SetNumber: Insert a number, and update the selected flag accordingly. Note that if formatOnDisplay is enabled, this will attempt to format the number according to the nationalMode option.
  • WidgetId [Input Text]: The identifier of the Widget containing the phone number.
  • PhoneNumber [Input PhoneNumber]: The phone number to be set.
• setNumberAsynchronous: Calls setNumber asynchronous.
  • WidgetId [Input Text]: The identifier of the Widget containing the phone number.
  • PhoneNumber [Input PhoneNumber]: The phone number to be set asynchronously.