RHFMultiAutocompleteObject

RHFMultiAutocompleteObject is a multi-select Autocomplete for object-based options. Each option has a checkbox, there is a "Select All" row, and the stored value is the array of full option objects, not primitives.

Use RHFMultiAutocomplete when a string[] of one property is enough.

Usage

import RHFMultiAutocompleteObject, { RHFMultiAutocompleteObjectProps } from '@nish1896/rhf-mui-components/mui/multi-autocomplete-object';

options must be an array of objects, and both labelKey and valueKey are required. labelKey is the property used as each option's visible label, and valueKey identifies an option.

import { useForm } from 'react-hook-form';

type Country = { name: string; code: string; currency: string };

type FormValues = {
  countries: Country[];
};

const { control, handleSubmit } = useForm<FormValues>({
  defaultValues: { countries: [] }
});

<form onSubmit={handleSubmit(values => console.log(values.countries))}>
  <RHFMultiAutocompleteObject
    fieldName="countries"
    control={control}
    options={countryList}
    labelKey="name"
    valueKey="code"
    registerOptions={{
      validate: value => value.length > 0 || 'Select at least one country'
    }}
  />
</form>

Select All

A "Select All" row is added at the top of the menu. selectAllText changes its text and hideSelectAllOption removes it.

• Clicking it selects every available option and stores the full array of objects.
• When all options are selected, clicking it again clears the selection.
• Its checkbox is indeterminate when some, but not all, options are selected.

The internally injected "Select All" option is NOT included in the final form value. Only actual options are returned.

<RHFMultiAutocompleteObject
  fieldName="countries"
  control={control}
  options={countryList}
  labelKey="name"
  valueKey="code"
  selectAllText="All countries"
/>

Customizing individual options

renderOptionLabel customizes the label next to an option's checkbox, and getOptionDisabled disables options. checkboxProps and formControlLabelProps style every option row.

<RHFMultiAutocompleteObject
  fieldName="countries"
  control={control}
  options={countryList}
  labelKey="name"
  valueKey="code"
  renderOptionLabel={option => `${option.name} (${option.currency})`}
  getOptionDisabled={option => option.currency === 'EUR'}
  checkboxProps={{ size: 'small' }}
/>

Limiting chips, loading and the input

limitTags, getLimitTagsText and ChipProps control the chips while the field is not focused. loading shows a spinner while options are fetched, disableClearable removes the clear button, and textFieldProps is forwarded to the underlying TextField.

<RHFMultiAutocompleteObject
  fieldName="countries"
  control={control}
  options={countryList}
  labelKey="name"
  valueKey="code"
  limitTags={3}
  loading={isFetchingCountries}
  textFieldProps={{ placeholder: 'Search countries' }}
/>

Handling value changes

onValueChange runs after the new array of objects has been stored in the form. It receives { newValue, selectedOption }:

<RHFMultiAutocompleteObject
  fieldName="countries"
  control={control}
  options={countryList}
  labelKey="name"
  valueKey="code"
  onValueChange={({ newValue, selectedOption }) => {
    setCurrencies(newValue.map(country => country.currency));
  }}
/>

Use customOnChange when you need to change what gets stored. It replaces the default handling, so you must call rhfOnChange yourself with the array to store. This example limits the selection to three countries: onValueChange is not called when customOnChange is used.

<RHFMultiAutocompleteObject
  fieldName="countries"
  control={control}
  options={countryList}
  labelKey="name"
  valueKey="code"
  customOnChange={({ rhfOnChange, newValue, selectedOption }) => {
    if (newValue.length <= 3) {
      rhfOnChange(newValue);
    }
  }}
/>

The label, helper text and error props work as described in RHFTextField.

Examples

• RHFMultiAutocompleteObject

API

The RHFMultiAutocompleteObjectProps interface extends AutocompleteProps and accepts the following additional props. Props marked with * are required.

Source Code

View the full implementation of this component on GitHub.