RHFPhoneInput

The RHFPhoneInput component is built on top of react-international-phone, a React library for handling international phone numbers.

It integrates with Material UI by leveraging the TextField component with the usePhoneInput hook from react-international-phone, allowing users to select a country and enter phone number in the appropriate international format.

Installation

npmyarnpnpm

npm install react-international-phone

yarn add react-international-phone

pnpm add react-international-phone

Usage

import RHFPhoneInput, {
  type RHFPhoneInputProps,
  type RHFPhoneInputValue
} from '@nish1896/rhf-mui-components/misc/phone-input';

<RHFPhoneInput
  fieldName="contactNumber"
  control={control}
  phoneInputProps={{
    defaultCountry: "in",
    preferredCountries: ["in", "us", "au"]
  }}
/>

Info

For validation, consider enforcing the following minimum lengths:

phone and phoneNo: at least 6 characters
country: exactly 2 characters (ISO country code)
dialCode: typically 1–4 digits, depending on the selected country

Return Value

The field value is represented as an RHFPhoneInputValue object:

type RHFPhoneInputValue = {
  phone: string;
  country: CountryIso2;  // imported from 'react-international-phone'
  dialCode: string;
  phoneNo: string;
}

After input, the returned phone value has this shape:

{
  phone: "+918885511000"
  country: "in"
  dialCode: "91"
  phoneNo: "8885511000"
}

Where:

Property	Description
`phone`	Full phone number including country dial code
`country`	Selected ISO 3166-1 alpha-2 country code
`dialCode`	Country dialing code without the `+` prefix
`phoneNo`	National phone number without the dial code

Why is the country stored separately?

Some countries share the same dialing code. For example:

United States: +1 (765) 232-3423
Canada: +1 (416) 345-6234
Puerto Rico: +1 (787) 234-4442

Although all three numbers begin with +1, they belong to different countries. Storing the selected country separately removes that ambiguity and makes it easier to perform country-specific validation and processing.

For example:

const { phone, country, phoneNo } = value;

Use:

phone when you need the complete international number.
phoneNo when you only need the national number.
country for country-specific logic or validation.

Search Countries

Because the country list is large, the component includes an inline search field that allows users to search for and select their preferred country. The search matches the country name, ISO2 country code, and dial code.

The search field is enabled by default and can be customized using searchCountryProps, an object with the following properties:

allowCountrySearch - Shows or hides the inline search field. Defaults to true.
textFieldProps - TextFieldProps for customizing the search text field.
renderCountryMenuItem - Customizes the content of each MenuItem in the country search dropdown.
noCountryFoundText - Text shown when no countries match the search. Defaults to "No countries found".

<RHFPhoneInput
  fieldName="phoneNumber"
  control={control}
  searchCountryProps={{
    textFieldProps: {
      variant: 'outlined'
    },
    renderCountryMenuItem: country => `${country.dialCode} - ${country.name}`,
    noCountryFoundText: 'No matching country found'
  }}
/>

The search field is rendered inside the country dropdown and remains pinned to the top while the country list is scrolled.

Examples

API

RHFPhoneInput extends the props of TextField and accepts the following additional props. Props marked with * are required.

Name	Type	Description
`fieldName`*	`string`	Name of the field registered with React Hook Form. This prop is required for all components.
`control`*	UseFormControl	The control option yielded on calling the useForm hook.
`registerOptions`	`RegisterOptions`	React Hook Form validation rules. Useful when not using a schema validation library such as Yup or Joi.
`customOnChange`	`({ rhfOnChange, newValue, phoneData }) => void`	Custom change handler that overrides the default phone value update behavior. Receives `rhfOnChange`, the structured `RHFPhoneInputValue`, and the raw change payload from `react-international-phone`. When provided, you must call `rhfOnChange` manually to update the form value.
`onValueChange`	`({ newValue, phoneData }) => void`	Optional callback fired after the phone value changes and the structured `RHFPhoneInputValue` is stored in the form field. Receives the updated value and the raw change payload from `react-international-phone`.
`countrySelectProps`	SelectProps	Props forwarded to the internal Select that renders the flag/dial-code trigger and country dropdown. Added in `v4.3`.
`searchCountryProps`	`{ allowCountrySearch, textFieldProps, renderCountryMenuItem, noCountryFoundText, menuItemProps }`	Props to customize the country search field and country menu item rendering. Added `menuItemProps` in `v4.3`.
`label`	`ReactNode`	The text to render in the FormLabel component. By default, the value of `fieldName` is transformed (e.g., "firstName" to "First Name") using the fieldNameToLabel function.
`showLabelAboveFormField`	`boolean`	Render form label above the form field in FormLabel component.
`formLabelProps`	FormLabelProps	FormLabelProps to customise FormLabel component for a field. Multiple fields can be configured using the ConfigProvider component.
`hideLabel`	`boolean`	Hides the FormLabel component if you don’t want to display the default form label component or prefer to render a fully custom label instead.
`required`	`boolean`	Indicates that the field is mandatory by adding an asterisk symbol (*) to the `formLabel`. This visual cue helps users quickly identify required fields in the form.
`renderError`	`(error: FieldError) => ReactNode`	Custom renderer for the React Hook Form field error. Receives the current field error and returns the content to display, such as `error.message` or a custom React element in the `HelperText` component. Added in `v4.1.0`.
`hideErrorMessage`	`boolean`	A flag to prevent replacement of helper text of a field by the `errorMessage` when the validation is triggered.
`helperText`	`ReactNode`	The content to display within the FormHelperText component below the field. If the field validation fails, this content will be overridden by the corresponding error message.
`formHelperTextProps`	FormHelperTextProps	FormHelperTextProps to customise FormHelperText component for a field. Multiple fields can be configured using the ConfigProvider component.
`phoneInputProps`	UsePhoneInputConfig	Props to pass in the `usePhoneInput` hook for customization.
`customIds`	`{ field, label, helperText, error }`	Overrides the default field, label, helper text, and error IDs used for accessibility.

Source Code

View the full implementation of this component on GitHub.

Rich Text Editor

Customization