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

For options as an array of objects:

<MUIAutocomplete
  fieldName="countriesVisited"
  options={countryList} // imported from MUICountrySelect
  labelKey="name"
  valueKey="iso3"
/>

Note

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

Props#

MUIAutocompleteProps 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.
`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`	`string \| 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.
`options`*	`string[] \| object[]`	An array with string or object values. Make sure to pass `labelKey` and `valueKey` when options is an array of objects.
`labelKey`	`string`	Property name used as the visible label for each option. Required when `options` is an array of objects.
`valueKey`	`string`	Property name used to derive the exposed value for each option. Required when `options` is an array of objects.
`multiple`	`boolean`	When true, allows selecting multiple values.
`disableClearable`	`boolean`	When true, the selected value cannot be cleared from the input. Default: `false`
`freeSolo`	`boolean`	When true, the user may type any value not present in `options`. The typed string is passed to `onValueChange` as-is.
`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.
`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.
`hideLabel`	`boolean`	When true, hides the rendered field label while preserving accessible labeling where possible.
`formLabelProps`	FormLabelProps	FormLabelProps forwarded to the internal `FormLabel`. The `id` is managed by the component. Multiple fields can be configured using the `ConfigProvider` component.
`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#

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

Reference#

MUI Autocomplete

Native Select

Autocomplete Object