RHFAutocompleteObject

RHFAutocompleteObject is an Autocomplete that stores the complete option object in your form, rather than a primitive.

A common use case is picking a record when you need more than its ID later. In an "Assign reviewer" form, the options are users loaded from an API, such as { id, name, email, role }. RHFAutocompleteObject shows each name and stores the selected user object itself, so the rest of the form can use the email for a confirmation message or the role for validation, without searching the list again for the matching ID.

It also suits edit forms. The saved reviewer can come back from the API as a fresh object and still be shown as selected, because options are matched by valueKey rather than by object identity.

Key Differences

Usage

import RHFAutocompleteObject, { RHFAutocompleteObjectProps } from '@nish1896/rhf-mui-components/mui/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. The stored value is the whole option object.

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

type User = {
  id: number;
  name: string;
  email: string;
  role: string
};

type FormValues = {
  reviewer: User | null;
};

const { control, handleSubmit } = useForm<FormValues>({
  defaultValues: { reviewer: null }
});

<form onSubmit={handleSubmit(values => console.log(values.reviewer?.email))}>
  <RHFAutocompleteObject
    fieldName="reviewer"
    control={control}
    options={users}
    labelKey="name"
    valueKey="id"
    registerOptions={{ required: 'Please pick a reviewer' }}
  />
</form>

Given these options:

const countryList = [
  { name: 'India', code: 'IN', currency: 'INR' },
  { name: 'Canada', code: 'CA', currency: 'CAD' }
];

the stored value is a single object ({ name: 'India', code: 'IN', currency: 'INR' }) or, with multiple, an array of them.

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

Multiple selection

Set multiple to store an array of objects, shown as chips. Use [] as the default value. limitTags, getLimitTagsText and ChipProps work as in RHFAutocomplete.

<RHFAutocompleteObject
  fieldName="reviewers"
  control={control}
  options={users}
  labelKey="name"
  valueKey="id"
  multiple
  limitTags={3}
  registerOptions={{
    validate: value => value.length > 0 || 'Pick at least one reviewer'
  }}
/>

Reading the selected object

Because the full object is stored, you can derive other UI from it with useWatch:

const reviewer = useWatch({ control, name: 'reviewer' });

<RHFAutocompleteObject
  fieldName="reviewer"
  control={control}
  options={users}
  labelKey="name"
  valueKey="id"
/>

{reviewer && <p>We will email {reviewer.email}</p>}

Clearing, loading and the input

disableClearable removes the clear button, so give the field an initial value. loading shows a spinner while options are fetched, and circularProgressProps customizes it. textFieldProps is forwarded to the underlying TextField.

<RHFAutocompleteObject
  fieldName="reviewer"
  control={control}
  options={users}
  labelKey="name"
  valueKey="id"
  loading={isFetchingUsers}
  circularProgressProps={{ size: 16 }}
  textFieldProps={{ placeholder: 'Search reviewers', size: 'small' }}
/>

Handling value changes

onValueChange runs after the selected object has been stored in the form. It receives { newValue, event, reason, details }, so you can use the whole object, not just an ID:

<RHFAutocompleteObject
  fieldName="reviewer"
  control={control}
  options={users}
  labelKey="name"
  valueKey="id"
  onValueChange={({ newValue, event, reason, details }) => setValue('reviewerEmail', newValue?.email ?? '')}
/>

Use customOnChange when you need to change what gets stored. It replaces the default handling, so you must call rhfOnChange yourself with the value to store. This example refuses to select an inactive user: onValueChange is not called when customOnChange is used.

<RHFAutocompleteObject
  fieldName="reviewer"
  control={control}
  options={users}
  labelKey="name"
  valueKey="id"
  customOnChange={({ rhfOnChange, newValue, event, reason, details }) => {
    if (newValue?.role === 'REVIEWER') {
      rhfOnChange(newValue);
    }
  }}
/>

Examples

• Autocomplete Variations
• RHFAutocompleteObject

API

The RHFAutocompleteObjectProps 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.