MUIMultiAutocomplete

MUIMultiAutocomplete is a multi-select Autocomplete rendering each option with a checkbox and an optional "Select All" row. It stores an array of string values.

This feature is particularly useful for scenarios where users need to handle bulk selections, such as assigning multiple tags, selecting categories, or choosing items in batch operations. The implementation stays flexible while preserving the same validation, customization, and styling options as MUIAutocomplete.

Use MUIMultiAutocompleteObject when you need to store full option objects.

Note

Even though freeSolo prop is supported, but is not compatible with selectAllText and will hide the "Select All" option.

When using freeSolo with object-based options, custom renderers such as renderValue, renderTags, or renderOptionLabel should handle both option objects and user-entered string values. A common approach is:

typeof value === 'string'

to distinguish free-form input from predefined option objects.

Usage#

import MUIMultiAutocomplete, {
  MUIMultiAutocompleteProps
} from '@nish1896/mui-components/mui/multi-autocomplete';

const [skills, setSkills] = useState<string[]>([]);

<MUIMultiAutocomplete
  fieldName="skills"
  value={skills}
  onValueChange={({ newValue }) => setSkills(newValue)}
  options={['React', 'Vue', 'Angular', 'Svelte']}
/>

Props#

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[]`	Currently selected string values (normalized with `valueKey` for object options). Always an array — `undefined` or `[]` is an empty selection, and clearing emits `[]` rather than `null`.
`onValueChange`*	`({ newValue, selectedOption }) => void`	Called on every selection change with the next string array and the option value that triggered the change (or the select-all sentinel).
`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.
`freeSolo`	`boolean`	When true, the user may type any value not present in `options`. Not compatible with `selectAllText` — enabling it hides the "Select All" option.
`disableClearable`	`boolean`	When true, the selected value cannot be cleared from the input. Default: `false`
`selectAllText`	`string`	Text to display for the "Select All" option. Default: `'Select All'`
`hideSelectAllOption`	`boolean`	When true, hides the select-all option.
`renderOptionLabel`	`(option, state) => ReactNode`	Render the option label content corresponding to each checkbox.
`getOptionDisabled`	`(option) => boolean`	Function used to determine whether an option should be disabled. Return `true` to disable the option and prevent it from being selected.
`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`.
`checkboxProps`	CheckboxProps	CheckboxProps passed down to each Checkbox component — custom color, size, etc.
`formControlLabelProps`	FormControlLabelProps	FormControlLabelProps forwarded to the internal `FormControlLabel`. Multiple fields can be configured using the `ConfigProvider` component.
`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.
`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#

Integrated with Formik — a checkbox multi-select storing a string[] with selectAllText, limitTags and checkboxProps, plus object options with getOptionDisabled.

Reference#

Autocomplete with Checkboxes

Country Select

Multi Autocomplete Object