RHFMultiAutocomplete

RHFMultiAutocomplete is an enhanced version of RHFAutocomplete that supports selecting multiple options from a dataset. It also includes a "Select All" feature, allowing users to quickly select all available options with a single click.

This feature is particularly useful for scenarios where users need to handle bulk selections, such as assigning multiple tags, selecting categories, or choosing items in batch operations. The implementation stays flexible while preserving the same validation, customization, and styling options as RHFAutocomplete.

Note

Starting with v4, the freeSolo prop is supported in RHFMultiAutocomplete, allowing users to enter values that are not present in the provided options.

When freeSolo is enabled, the Select All option is automatically hidden. This is intentional because the field can contain both predefined values and custom user-entered values, so selecting "all" only from the predefined options can create confusing behavior.

When using freeSolo with object-based options, custom renderers such as renderValue, renderTags, or renderOptionLabel should handle both option objects and user-entered string values. A common approach is:

typeof value === 'string'

to distinguish free-form input from predefined option objects.

Usage

import RHFMultiAutocomplete, { RHFMultiAutocompleteProps } from '@nish1896/rhf-mui-components/mui/multi-autocomplete';

<RHFMultiAutocomplete
  fieldName="countriesVisited"
  control={control}
  options={['Azerbaijan', 'Canada', 'India']}
/>

For options as an array of objects:

<RHFMultiAutocomplete
  fieldName="countriesVisited"
  control={control}
  options={countryList} // imported from RHFCountrySelect
  labelKey="name"
  valueKey="iso"
/>

Warning

When using an array of objects for options, both labelKey and valueKey are required. If either is missing, an error will be thrown.

Examples

API

The RHFMultiAutocompleteProps 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.
`options`*	`string[] / object[]`	An array with string or object values. Make sure to pass `labelKey` and `valueKey` when options is an array of objects.
`labelKey`	`string`	Property name used as the visible label for each option. Required when `options` is an array of objects.
`valueKey`	`string`	Property name used as the stored value for each option. Required when `options` is an array of objects.
`freeSolo`	`boolean`	Allows users to enter values that are not present in the autocomplete options. Supported from v4 onwards.
`customOnChange`	`({ rhfOnChange, newValue, selectedOption }) => void`	Override the default `onChange` behavior of the multi-autocomplete.
`onValueChange`	`({ newValue, selectedOption }) => void`	Returns the latest value of the field in `newValue` parameter. The last selected option can be obtained from `selectedOption`.
`selectAllText`	`string`	Custom text to render in place of the "Select All" option that enables user to select all available options in the Autocomplete.
`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, state) => ReactNode`	Render the option label content corresponding to each checkbox.
`checkboxProps`	CheckboxProps	Checkbox Props used to customize the checkbox rendered alongside each autocomplete option.
`formControlLabelProps`	FormControlLabelProps	FormControlLabelProps to customise `FormControlLabel` component for a field. Multiple fields can be configured using the ConfigProvider component.
`circularProgressProps`	CircularProgressProps	Props forwarded to the CircularProgress displayed in the autocomplete input when it is `loading`. Added in `v4.3`.
`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.

Country Select

Multi Autocomplete Object