MUIAutocompleteObject
MUIAutocompleteObject is an
Autocomplete that stores the
complete option object 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 }. MUIAutocompleteObject 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. MUIAutocomplete,
which stores a single property, would leave you to do that lookup.
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.
freeSolo is intentionally unsupported to keep the value type predictable —
use MUIAutocomplete or
MUIMultiAutocomplete instead.
Usage
import MUIAutocompleteObject, {
MUIAutocompleteObjectProps
} from '@nish1896/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 value. value is the whole option
object.
const [user, setUser] = useState<User | null>(null);
<MUIAutocompleteObject
fieldName="user"
options={users}
labelKey="name"
valueKey="id"
value={user}
onValueChange={({ newValue, event, reason, details }) => setUser(newValue)}
/>onValueChange receives { newValue, event, reason, details }: the
selected object (or objects) as Material UI reports them, the original
event, MUI's change reason and extra details. There is no
selectedOption, because newValue already has the selected option.
Multiple selection
Set multiple to store an Option[] and show each selection as a chip. The
menu stays open while the user picks, whereas a single select closes and blurs
after a choice.
While the field is not focused, only the first limitTags chips (default 2)
are shown, followed by a "+N More" chip. limitTags={-1} shows all of them,
and getLimitTagsText receives the number of hidden chips and returns your own
text. ChipProps customizes the chips.
const [members, setMembers] = useState<User[]>([]);
<MUIAutocompleteObject
fieldName="members"
options={users}
labelKey="name"
valueKey="id"
value={members}
onValueChange={({ newValue }) => setMembers(newValue)}
multiple
limitTags={3}
getLimitTagsText={hiddenCount => `+${hiddenCount} members`}
ChipProps={{ color: 'primary', size: 'small' }}
/>Clearing the value
A clear button is shown once there is a value. disableClearable removes it,
so newValue is never null and the value type no longer includes null.
Give the field an initial value in that case.
const [user, setUser] = useState<User>(users[0]);
<MUIAutocompleteObject
fieldName="user"
options={users}
labelKey="name"
valueKey="id"
value={user}
onValueChange={({ newValue }) => setUser(newValue)}
disableClearable
/>Loading state
Set loading while the options are being fetched. A small spinner appears at
the end of the input, and when there are no options yet, the popup shows the
loading text (loadingText, Loading… by default) instead of "No options".
circularProgressProps customizes the spinner, which is 20px by default.
<MUIAutocompleteObject
fieldName="user"
options={users}
labelKey="name"
valueKey="id"
value={user}
onValueChange={({ newValue }) => setUser(newValue)}
loading={isFetchingUsers}
circularProgressProps={{ size: 16 }}
/>Customizing the input
textFieldProps is forwarded to the underlying TextField, for example
a placeholder, variant or size. autoHighlight is true by default,
which differs from Material UI, so the first option is highlighted as the
user types and Enter selects it. Pass autoHighlight={false} to turn that off.
A ref gives you the input element.
const inputRef = useRef<HTMLInputElement>(null);
<MUIAutocompleteObject
fieldName="user"
options={users}
labelKey="name"
valueKey="id"
value={user}
onValueChange={({ newValue }) => setUser(newValue)}
ref={inputRef}
autoHighlight={false}
textFieldProps={{ placeholder: 'Search users', size: 'small' }}
/>API
MUIAutocompleteObjectProps also accepts most
AutocompleteProps.
Props marked with * are required.
| Name | Type | Description |
|---|---|---|
fieldName* | string | Name/path of the field. Used to derive the id, the default label, and the name attribute. This prop is required for all components. |
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 | Property name used as the visible label for each option. |
valueKey* | string | Property name used to compare options with the current value. |
ref | Ref<HTMLInputElement> | Forwarded ref for the underlying MUI TextField's input element — use it to imperatively focus the field or read its DOM node. |
value | Option | Option[] | null | Currently selected option object(s): Option[] when multiple is true, otherwise a single Option. A cleared single selection emits null (unless disableClearable); a cleared multi-selection emits [], never null. |
onValueChange* | ({ newValue, event, reason, details }) => void | Called on every selection change with the selected object value(s) from MUI, without reducing them to valueKey. |
multiple | boolean | When true, allows selecting multiple values. |
disableClearable | boolean | When true, the selected value cannot be cleared from the input.Default: false |
autoHighlight | boolean | When true, the first option is highlighted while the user types, so pressing Enter selects it.Default: true |
loading | boolean | When true, a small spinner is shown at the end of the input and, when there are no options, the popup shows the loading text (loadingText, default Loading…) instead of "No options". Customize the spinner with circularProgressProps. |
limitTags | number | Maximum number of selected values shown as chips when the input is not focused. Set -1 to disable the limit.Default: 2 |
getLimitTagsText | (more: number) => ReactNode | Custom label rendered for the hidden selections counter. Receives the number of hidden values. |
textFieldProps | TextFieldProps | TextFieldProps forwarded to the internal MUI TextField. |
ChipProps | ChipProps | ChipProps forwarded to chips rendered for selected values. |
circularProgressProps | CircularProgressProps | CircularProgressProps forwarded to the loading spinner shown while loading is true — custom color, size, etc.Added in v2. |
label | ReactNode | Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name". |
showLabelAboveFormField | boolean | When true, renders the field label above the form field in the FormLabel component, instead of inside or beside it. Takes precedence over allLabelsAboveFields from the ConfigProvider, so false keeps the label inside this field even when the config places every label above its field. |
formLabelProps | FormLabelProps | FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
hideLabel | boolean | When true, hides the rendered field label while preserving accessible labeling where possible. |
required | boolean | Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes. |
errorMessage | string | string[] | Validation error for the field — pass a single message string, or a string[] when the field can fail multiple rules at once (every message is shown together). A non-empty string or array puts the field in an error state; undefined/''/[] clear it.Normalize your form library's error shape to this at the call site (e.g. an RHF FieldError via its .message). Use renderError to customize how the message(s) are rendered. |
renderError | (errors: string[]) => ReactNode | Custom renderer for the resolved error message(s), called only when the field is in an error state. Always receives a string[] — use errors[0] for the common single-message case, or map over errors when a field fails several rules. By default a single message renders as text and multiple messages render on separate lines. |
hideErrorMessage | boolean | If true, hides the error message text while keeping the field in an error state. |
helperText | ReactNode | Content displayed in the FormHelperText component below the field when there is no visible validation error. |
formHelperTextProps | FormHelperTextProps | FormHelperTextProps forwarded to the internal FormHelperText. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
customIds | { field, label, helperText, error } | Overrides the default field, label, helper text, and error IDs used for accessibility. |
Playground
Driven by plain React state — stores the whole selected object; a single select
(labelKey / valueKey) and a multi-select with limitTags and ChipProps.
Reference
Source Code
View the full implementation of this component on GitHub.