Skip to main content

Phone

Base​

Initially selected country​

Based on phone number​

danger

The initial value of the value or defaultValue properties must start with the character +, followed by the country code.

The country initially selected will be identified mainly by the telephone number passed to the value or defaultValue properties, during component initialization.

The absence of any of this information may prevent the component from automatically identifying the country, causing an alert to be displayed, as in the example below:

Based on defaultCountry property value​

It is also possible to indicate the selected country via the defaultCountry property, entering the country code in two-digit ISO format.

Based on the default browser language​

If no value is passed to the value, defaultValue or defaultCountry properties, the selected country will be automatically identified based on the default language of the user's browser.

Adaptable masks​

When entering the phone number, the Phone component automatically adjusts the mask to the proper format - when the selected country has more than one applicable format.

As is the case in Brazil, which has a format for landlines ((99) 9999-9999) and another for mobile numbers ((99) 99999-9999).

Uncontrolled vs. Controlled​

Unlike other form components, Phone does not support a controlled version.

Enabling this type of control would conflict with the existence of masks for phone formats in different countries.

For this reason, the value property is just an alias for the defaultValue property and exists to maintain consistency with other form components.

See in the example below how the Phone component can be used simulating a controlled behavior in a real scenario.

Form events​

All key component interaction events (onChange, onClear, onBlur and onFocus) expect callbacks that support the same types of parameters, in order:

  1. The object for the triggered event
  2. The value of the field without the mask and with the country code
  3. General information about the status of the component, such as selected country, validity of the entered value, among others
danger

Do not use the target.value property, coming from the event object, to change the state of the form. This argument receives the field value as present in the input, that is, with a mask and without the country code.

The second argument is more suitable for changing the state of the form, as its value corresponds to the phone number entered, without a mask and with the country code. Therefore, it is in the proper format to input the value and defaultValue properties and to be stored in databases.

For more details go to our Component API tab.

Error feedback and validations​

The error property allows displaying the component as invalid.

Integration with Form.Control​

As with other form components, the Phone component is integrated with the Form.Control component and receives the error property automatically through this integration.

Validating the phone number​

The validation of the entered number can be checked in each of the events mentioned above, through the valid attribute, present in the object with additional information. This information can be used to validate the phone number entered by the user.

React Hook Form​

Use the Phone component together with the React Hook Form. To do this, install this dependency in the project.

yarn add react-hook-form

See and test the full example below:

function ExampleWithReactHookForm() {
  const { control, watch } = useForm();
  const name = 'phone';

  return (
    <Form.Control>
      <Controller
        control={control}
        name={name}
        defaultValue={null}
        render={({ onChange }) => (
          <Phone
            id={name}
            name={name}
            onClear={() => onChange('')}
            onChange={(_, phone) => onChange(phone)}
          />
        )}
      />

      <Form.Feedback>{watch(name)}</Form.Feedback>
    </Form.Control>
  );
}

Internationalization​

It is possible to pass custom values for the different texts used internally by the component. Are they:

  • countryNames: Custom country names
  • countryCallingCodeLabelText: Custom text to label the country code. This text is not displayed but is useful for accessibility
  • selectedCountryLabelText: Custom text to label the country selection. This text is not displayed but is useful for accessibility
  • clearLabelText: Custom text to label the clear button. This text is not displayed but is useful for accessibility
  • unidentifiedCountryTooltip: Custom text for the Tooltip, displayed when the country has not been properly identified (see section Initially selected country)
danger

When changing the component's default language (English), values must be set for all available constants.

To help with this process, constants are available with default values for these properties - in English, Portuguese and Spanish. For more details go to our Component API tab.

Below is an example of using these constants for Portuguese:

Feedback​