MUI Components
NPM

MUIAutocomplete

MUIAutocomplete wraps the Material UI Autocomplete and stores primitive values (the option string, or the valueKey property for object options). It supports single or multiple selection, disableClearable and freeSolo.

Use MUIAutocompleteObject when you need to store the full option object.

Usage

import MUIAutocomplete, {
  MUIAutocompleteProps
} from '@nish1896/mui-components/mui/autocomplete';
const [color, setColor] = useState<string | null>(null);

<MUIAutocomplete
  fieldName="color"
  options={['Red', 'Green', 'Blue']}
  value={color}
  onValueChange={({ newValue, selectedOption, event, reason, details }) => setColor(newValue)}
/>

A single select stores a string, or null when nothing is selected, and multiple stores a string[]. undefined, null and [] all mean no selection. A value that doesn't match any option isn't displayed, unless freeSolo is on.

onValueChange receives { newValue, selectedOption, event, reason, details }. newValue is the normalized value to store, and selectedOption is the raw Material UI selection: the option object, or the typed string with freeSolo. event, reason (such as selectOption, removeOption, clear or createOption) and details come straight from the Material UI change handler.

With an array of objects

Options can also be objects. In this case, both labelKey and valueKey are required. labelKey is the property used as each option's visible label, and valueKey is the property used as its value. value then holds the valueKey property of the selected option, not the whole object.

To store the whole object, use MUIAutocompleteObject instead.

const [countryCode, setCountryCode] = useState(null);

<MUIAutocomplete
  fieldName="countriesVisited"
  options={countryList} // imported from MUICountrySelect
  labelKey="name"
  valueKey="iso3"
  value={countryCode}
  onValueChange={({ newValue }) => setCountryCode(newValue)}
/>

Multiple selection

Set multiple to store a string[] 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 [skills, setSkills] = useState<string[]>([]);

<MUIAutocomplete
  fieldName="skills"
  options={['React', 'Vue', 'Angular', 'Svelte', 'Solid']}
  value={skills}
  onValueChange={({ newValue }) => setSkills(newValue)}
  multiple
  limitTags={3}
  getLimitTagsText={hiddenCount => `+${hiddenCount} skills`}
  ChipProps={{ color: 'primary', size: 'small' }}
/>

Free text entry

freeSolo lets the user enter a value that isn't in options. The typed string is passed to onValueChange as it is and stored in value. autoSelect defaults to true with freeSolo, so text typed in the field is committed when it loses focus. Pass autoSelect={false} to require Enter. With multiple, each typed value becomes its own chip.

const [city, setCity] = useState<string | null>(null);

<MUIAutocomplete
  fieldName="city"
  options={['Delhi', 'Mumbai', 'Pune']}
  value={city}
  onValueChange={({ newValue }) => setCity(newValue)}
  freeSolo
/>
Note

When using freeSolo with object-based options, custom renderers such as renderValue, renderTags, or renderOption 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.

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 [color, setColor] = useState('Red');

<MUIAutocomplete
  fieldName="color"
  options={['Red', 'Green', 'Blue']}
  value={color}
  onValueChange={({ newValue }) => setColor(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.

<MUIAutocomplete
  fieldName="user"
  options={users}
  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);

<MUIAutocomplete
  fieldName="color"
  options={['Red', 'Green', 'Blue']}
  value={color}
  onValueChange={({ newValue }) => setColor(newValue)}
  ref={inputRef}
  autoHighlight={false}
  textFieldProps={{ placeholder: 'Pick a colour', size: 'small' }}
/>

API

MUIAutocompleteProps also accepts most AutocompleteProps.

Props marked with * are required.

NameTypeDescription
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*string[] | object[]
An array with string or object values. Make sure to pass labelKey and valueKey when options is an array of objects.
labelKeystring
Property name used as the visible label for each option. Required when options is an array of objects.
valueKeystring
Property name used to derive the exposed value for each option. Required when options is an array of objects.
refRef<HTMLInputElement>
Forwarded ref for the underlying MUI TextField's input element — use it to imperatively focus the field or read its DOM node.
valuestring | string[] | null
Currently selected value(s): string[] when multiple is true, otherwise a string (normalized with valueKey for object options). A cleared single selection emits null (unless disableClearable); a cleared multi-selection emits [], never null.
onValueChange*({ newValue, selectedOption, event, reason, details }) => void
Called on every selection change with the normalized value and the raw MUI selection metadata. newValue is string[] when multiple is true, otherwise string, and includes null only when clearing is allowed.
multipleboolean
When true, allows selecting multiple values.
disableClearableboolean
When true, the selected value cannot be cleared from the input.
Default: false
freeSoloboolean
When true, the user may type any value not present in options. The typed string is passed to onValueChange as-is.
autoSelectboolean
When true, the highlighted option, or with freeSolo the typed text, is committed as the value when the input loses focus.
Default: true with freeSolo, otherwise false
autoHighlightboolean
When true, the first option is highlighted while the user types, so pressing Enter selects it.
Default: true
loadingboolean
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.
limitTagsnumber
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.
textFieldPropsTextFieldProps
TextFieldProps forwarded to the internal MUI TextField.
ChipPropsChipProps
ChipProps forwarded to chips rendered for selected values.
circularProgressPropsCircularProgressProps
CircularProgressProps forwarded to the loading spinner shown while loading is true — custom color, size, etc.
Added in v2.
labelReactNode
Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name".
showLabelAboveFormFieldboolean
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.
hideLabelboolean
When true, hides the rendered field label while preserving accessible labeling where possible.
formLabelPropsFormLabelProps
FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component.
requiredboolean
Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes.
errorMessagestring | 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.
hideErrorMessageboolean
If true, hides the error message text while keeping the field in an error state.
helperTextReactNode
Content displayed in the FormHelperText component below the field when there is no visible validation error.
formHelperTextPropsFormHelperTextProps
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

Integrated with TanStack Form — a single free-solo select (string) and a multi-select (string[]) with limitTags, getLimitTagsText and ChipProps.

Single free-solo select with validation

Multi-select with limitTags & chip props

TypeScript

Autocomplete fetching options from API and appending more options on scrolling

Form State - Values & Errors

Reference

Source Code

View the full implementation of this component on GitHub.