MUICountrySelect

MUICountrySelect is an Autocomplete pre-loaded with a list of 250 countries (flag, name, dial code, ISO). Store the complete CountryDetails object, or a single property via valueKey. Pin common choices with preferredCountries.

Usage#

import MUICountrySelect, {
  MUICountrySelectProps,
  CountryISO,
  CountryDetails,
  countryList
} from '@nish1896/mui-components/mui/country-select';

MUICountrySelect returns the country property specified by valueKey. If valueKey is omitted, the complete country object is returned instead.

const [country, setCountry] = useState<CountryDetails | null>(null);

/* Returns "IN", "AU" */
<MUICountrySelect
  fieldName="country"
  value={country}
  onValueChange={({ newValue }) => setCountry(newValue)}
  preferredCountries={['US', 'GB', 'IN']}
/>

/**
 * Returns
 * {
 *   name: 'India',
 *   iso: 'IN',
 *   iso3: 'IND',
 *   emoji: '🇮🇳'
 * }
 */
<MUICountrySelect
  fieldName="nationality"
  value={nationality}
  valueKey="iso3"
  onValueChange={({ newValue }) => setNationality(newValue)}
  preferredCountries={['IN', 'US', 'AU']}
/>

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 the default identifier used for country option values, providing a compact and consistent way to store selections. The iso key 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)
);

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

Props#

Pass valueKey (e.g. iso or name) to store a single country property instead of the full object. Props marked with * are required.

Name	Type	Description
`fieldName`*	`string`	Name/path of the field. Used to derive the `id`, the default label, and the `name` attribute. This prop is required for all components.
`ref`	`Ref<HTMLInputElement>`	Forwarded ref for the underlying MUI `TextField`'s input element — use it to imperatively focus the field or read its DOM node.
`value`	`CountryDetails \| CountryDetails[keyof CountryDetails] \| array \| null`	Currently selected country value(s): complete `CountryDetails` object(s), or the property named by `valueKey` when provided. Pass an array when `multiple` is true. A cleared single selection emits `null` (unless `disableClearable`); a cleared multi-selection emits `[]`, never `null`.
`onValueChange`*	`({ newValue, event, reason, details }) => void`	Called on every selection change with the normalized country value and the raw MUI Autocomplete change metadata.
`countries`	`CountryDetails[]`	List of countries to display in the country selector. Defaults to all countries from `countryList`.
`preferredCountries`	`CountryISO[]`	Country ISO codes pinned at the top of the dropdown, in the provided order.
`valueKey`	`name` \| `iso` \| `iso3`	When provided, selected value(s) are exposed using the specified country property; when omitted, complete country objects are used.
`multiple`	`boolean`	When true, allows selecting multiple values.
`disableClearable`	`boolean`	When true, the selected value cannot be cleared from the input. Default: `false`
`renderOptionLabel`	`(option: CountryDetails) => ReactNode`	Custom renderer for each country option in the dropdown. Receives the country object and should return the label/content to render.
`limitTags`	`number`	Maximum number of selected values shown as chips when the input is not focused. Set `-1` to disable the limit. Default: `2`
`getLimitTagsText`	`(more: number) => ReactNode`	Custom label rendered for the hidden selections counter. Receives the number of hidden values.
`textFieldProps`	TextFieldProps	TextFieldProps forwarded to the internal MUI `TextField`.
`ChipProps`	ChipProps	ChipProps forwarded to chips rendered for selected values.
`label`	`ReactNode`	Label displayed for the field. Defaults to a human-readable label derived from `fieldName`, e.g. `firstName` becomes `First Name`
`showLabelAboveFormField`	`boolean`	When true, renders the field label above the form field in the FormLabel component, instead of inside or beside it.
`formLabelProps`	FormLabelProps	FormLabelProps forwarded to the internal `FormLabel`. The `id` is managed by the component. Multiple fields can be configured using the `ConfigProvider` component.
`hideLabel`	`boolean`	When true, hides the rendered field label while preserving accessible labeling where possible.
`required`	`boolean`	Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes.
`errorMessage`	`string \| string[]`	Validation error for the field — pass a single message `string`, or a `string[]` when the field can fail multiple rules at once (every message is shown together). A non-empty string or array puts the field in an error state; `undefined`/`''`/`[]` clear it. Normalize your form library's error shape to this at the call site (e.g. an RHF `FieldError` via its `.message`). Use `renderError` to customize how the message(s) are rendered.
`renderError`	`(errors: string[]) => ReactNode`	Custom renderer for the resolved error message(s), called only when the field is in an error state. Always receives a `string[]` — use `errors[0]` for the common single-message case, or map over `errors` when a field fails several rules. By default a single message renders as text and multiple messages render on separate lines.
`hideErrorMessage`	`boolean`	If true, hides the error message text while keeping the field in an error state.
`helperText`	`ReactNode`	Content displayed in the FormHelperText component below the field when there is no visible validation error.
`formHelperTextProps`	FormHelperTextProps	FormHelperTextProps forwarded to the internal `FormHelperText`. The `id` is managed by the component. Multiple fields can be configured using the `ConfigProvider` component.
`customIds`	`{ field, label, helperText, error }`	Overrides the default field, label, helper text, and error IDs used for accessibility.

Playground#

Driven by plain React state — a single select with preferredCountries and a flag renderOptionLabel, and a multi-select with limitTags and ChipProps.

Reference#

Country select

Autocomplete Object

Multi Autocomplete