RHFAutocomplete

RHFAutocomplete extends Autocomplete and is designed for searching and selecting options from large datasets. Similar to RHFSelect, it supports selecting single or multiple options and accepts options as an array of strings or an array of objects. This component is ideal for use cases that require dynamic filtering or large option lists.

Note

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

When using freeSolo with object-based options, custom renderers such as renderValue, renderTags, or renderOptionLabel should account for 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 RHFAutocomplete, { RHFAutocompleteProps } from '@nish1896/rhf-mui-components/mui/autocomplete';

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

For options as an array of objects:

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

Warning

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

You can extend or reuse the RHFAutocomplete component by creating your own wrapper component.

/**
 * The below code snippet illustrates how to create a reusable styled Autocomplete
 * component using RHFAutocomplete, which can be used throughout the application.
 *
 * A similar approach can be taken to create reusable styled components for:
 * - RHFAutocompleteObject
 * - RHFMultiAutocomplete
 * - RHFMultiAutocompleteObject
 */

import { type FieldValues } from 'react-hook-form';
import RHFAutocomplete, {
  type RHFAutocompleteProps
} from '@nish1896/rhf-mui-components/mui/autocomplete';
import type { StrObjOption } from '@nish1896/rhf-mui-components/types';

type StyledAutocompleteProps<
  T extends FieldValues,
  Option extends StrObjOption = StrObjOption,
  LabelKey extends Extract<keyof Option, string> = Extract<keyof Option, string>,
  ValueKey extends Extract<keyof Option, string> = Extract<keyof Option, string>,
  DisableClearable extends boolean = false,
  FreeSolo extends boolean = false
> = Omit<RHFAutocompleteProps<T, Option, LabelKey, ValueKey, true, DisableClearable, FreeSolo>, 'multiple'>;

const StyledAutocomplete = <
  T extends FieldValues,
  Option extends StrObjOption = StrObjOption,
  LabelKey extends Extract<keyof Option, string> = Extract<keyof Option, string>,
  ValueKey extends Extract<keyof Option, string> = Extract<keyof Option, string>,
  DisableClearable extends boolean = false,
  FreeSolo extends boolean = false
>({
  ...rest
}: StyledAutocompleteProps<T, Option, LabelKey, ValueKey, DisableClearable, FreeSolo>) => {
  return (
    <RHFAutocomplete
      formHelperTextProps={{
        sx: { fontColor: theme => theme.palette.info.main }
      }}
      multiple
      {...rest}
    />
  );
};

export default StyledAutocomplete;

Examples

API

The RHFAutocompleteProps 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.
`multiple`	`boolean`	Allows multiple values to be selected.
`freeSolo`	`boolean`	Allows users to enter values that are not present in the autocomplete options. Supported from v4 onwards.
`customOnChange`	`({ rhfOnChange, newValue, selectedOption, event, reason, details }) => void`	Override the default `onChange` behavior of the autocomplete.
`onValueChange`	`({ newValue, selectedOption, event, reason, details }) => void`	Returns the latest value of the field in `newValue` parameter. The last selected option can be obtained from `selectedOption`.
`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.
`textFieldProps`	TextFieldProps	Props to customise the Autocomplete Textfield.
`ChipProps`	ChipProps	Props applied to the Chip component used to render selected values.
`circularProgressProps`	CircularProgressProps	Props forwarded to the CircularProgress displayed in the autocomplete input when it is `loading`. Added in `v4.3`.
`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.

Native Select

Autocomplete Object

RHFAutocomplete

Usage

StyledAutocomplete.tsx

Examples

API

Source Code