RHFAutocompleteObject

RHFAutocompleteObject is available from version 3.3 and above.

RHFAutocompleteObject extends Autocomplete, designed for use cases where you need to work with the entire selected option object instead of just a primitive value.

Unlike RHFAutocomplete, which stores only the value derived from valueKey, this component stores and returns the full option object (or array of objects). This is particularly useful when additional metadata from the selected option is required elsewhere in your form or application.

Key Differences

Feature	RHFAutocomplete	RHFAutocompleteObject
Stored value	string / string[]	object / object[]
Requires labelKey	Optional	✅ Required
Requires valueKey	Optional	✅ Required
Use case	Simple forms	Metadata-driven forms

Usage

import RHFAutocompleteObject, { RHFAutocompleteObjectProps } from '@nish1896/rhf-mui-components/mui/autocomplete-object';

<RHFAutocompleteObject
  fieldName="country"
  control={control}
  options={countryList}
  labelKey="name"
  valueKey="code"
  multiple           // omit this prop for single selection
  errorMessage={errors?.country?.message}
/>

warning

Both labelKey and valueKey props are mandatory. Since this component works exclusively with object-based options, omitting either will result in an error.

This component does not support the freeSolo prop, similar to RHFAutocomplete. Users can only select values from the provided options.

Example Option Structure

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

Stored Value (Multiple)

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

When to Use

Use RHFAutocompleteObject when:

• You need access to additional fields from the selected option (e.g. currency, id, etc.)
• You want to avoid mapping IDs back to objects
• Your form logic depends on rich object data
• You are working with APIs that expect full objects instead of IDs

Examples

• RHFAutocompleteObject
• Autocomplete Variations

API

The RHFAutocompleteObjectProps interface extends AutocompleteProps and accepts the following additional props:

Name	Type	Required	Description
fieldName	string	✅	React Hook Form requires name as a key for the registration process. This is a required prop for all components.
control	UseFormControl	✅	The control option yielded on calling the useForm hook.
registerOptions	RegisterOptions		Register options for validation if using react-hook-form without any validation libraries like yup or Joi.
options	object[]	✅	An array of objects. labelKey and valueKey are required so the component knows which properties to use for the visible label and the stored value.
labelKey	string	✅	The key of object in options array, whose value would be shown as the label in the formfield.
valueKey	string	✅	The key of object in options array, whose value would be actual value of the option selected in the formfield.
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.
multiple	boolean		Allow selection of single or multiple values for a formfield.
onValueChange	(newValue, event, reason, details?) => void		Returns the entire object option(s) selected by the user in newValue parameter. The last selected option can be obtained from details.
label	ReactNode		The text to render in FormLabel component. By default, the value of fieldName such as firstName will be transformed to display "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.
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.
errorMessage	ReactNode		Error message to be shown for a field in FormHelperText component.
hideErrorMessage	boolean		A flag to prevent replacement of helper text of a field by the error message when the validation is triggered.
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.