RHFCountrySelect

RHFCountrySelect uses the Autocomplete component from Material UI to let users select one or more countries from a comprehensive list of 250 options. It can return the selected country as its name, ISO code, ISO3 code, or full country object. Each option is displayed with the corresponding country flag for a clearer selection experience.

Usage

import RHFCountrySelect, {
  RHFCountrySelectProps,
  CountryISO,
  CountryDetails,
  countryList
} from '@nish1896/rhf-mui-components/mui/country-select';

Note

From v4 onward, RHFCountrySelect returns the country property specified by valueKey. If valueKey is omitted, the complete country object is returned instead.

<RHFCountrySelect
  fieldName="nationality"
  control={control}
  valueKey="iso"
/>
// Returns "IN", "AU"

<RHFCountrySelect
  fieldName="countriesVisited"
  control={control}
/>
/**
 * Returns
 * {
 *   name: 'India',
 *   iso: 'IN',
 *   iso3: 'IND',
 *   emoji: '🇮🇳'
 * }
 */

Each option in the list of 250 countries is represented as an object structured as follows:

{
  name: 'India',
  iso: 'IN',
  iso3: 'IND',
  emoji: '🇮🇳'
}

The iso key is used to determine the preferred countries from the countryList. It is strongly typed as CountryISO, ensuring type safety and consistency during integration. You can also retrieve the name or iso3 value(s) by setting the desired key through the valueKey prop.

For developers who need access to all available country data, the complete list of countries is provided via the countryList export from this module.

The following code snippet demonstrates an advanced use case where users can select multiple countries by their names from a predefined list of country options. To improve usability, a set of preferred countries is prominently displayed at the top of the dropdown. This prioritization keeps frequently chosen options easily accessible and streamlines the selection process.

/* Logic for filtering countries */
const filteredCountries = countryList.filter(
  country => ['IN', 'US', 'AU', 'FI', 'UA', 'CN', 'GB', 'JP', 'VN'].includes(country.iso)
);

<RHFCountrySelect
  fieldName="dreamDestinations"
  control={control}
  valueKey="name"
  preferredCountries={['IN', 'AU', 'JP']}
  countries={filteredCountries}
  multiple
/>

Examples

API

The RHFCountrySelectProps interface extends AutocompleteProps 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.
`countries`	`CountryDetails[]`	The list of countries to render for selection in the Autocomplete. By default all countries will be listed.
`preferredCountries`	`CountryISO[]`	The countries to show at the top of the list. The array requires the `iso` values of the countries.
`valueKey`	`name` / `iso` / `iso3`	Determines which country property is stored as the selected value. If not provided, the complete country object is returned.
`multiple`	`boolean`	Allow selection of more than one countries
`customOnChange`	`({ rhfOnChange, newValue, event, reason, details? }) => void`	Custom change handler that overrides the default update behavior. Receives the updated value, the triggering event, and `rhfOnChange`. Use this to validate, transform, or conditionally update country selections before updating form state. When provided, you must call `rhfOnChange` manually.
`onValueChange`	`({ newValue, event, reason, details? }) => void`	Called when the selected country value changes. Returns the selected country property defined by `valueKey`, or the complete country object when `valueKey` is not provided. Returns an array when `multiple` is enabled and `null` when no selection is made.
`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.
`renderOptionLabel`	`(option: CountryDetails, state) => ReactNode`	Custom renderer for each country option in the dropdown. Receives the country object and should return the label/content to render. Option state param added in `v4.2.0`.
`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.
`textFieldProps`	TextFieldProps	Props to customise the Autocomplete Textfield.
`ChipProps`	ChipProps	Props applied to the Chip component used to render selected values.
`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.

Autocomplete Object

Multi Autocomplete