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.
Usage
import MUIMultiAutocomplete, {
MUIMultiAutocompleteProps
} from '@nish1896/mui-components/mui/multi-autocomplete';const [skills, setSkills] = useState<string[]>([]);
<MUIMultiAutocomplete
fieldName="skills"
options={['React', 'Vue', 'Angular', 'Svelte']}
value={skills}
onValueChange={({ newValue, selectedOption }) => setSkills(newValue)}
/>The type of value is a string[] when the options is an array of
strings, or the valueKey property for an array of objects. undefined,
null and [] all mean no selection, and clearing the field gives [].
Every option has a checkbox, and the menu stays open while the user picks.
Selected values are shown as chips.
onValueChange receives { newValue, selectedOption }: the next array,
and the value that triggered the change. The value of selectedOption is
'__ALL__' when "Select All" is toggled, and undefined when the field
is cleared. There is no event or reason, unlike MUIAutocomplete.
With an array of objects
Options can also be an array of objects, and 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 is then a string[] of the valueKey properties of the selected
options, not the whole objects.
To store the whole objects, use MUIMultiAutocompleteObject instead.
const [planIds, setPlanIds] = useState<string[]>([]);
<MUIMultiAutocomplete
fieldName="plans"
options={[
{ id: 'free', name: 'Free' },
{ id: 'pro', name: 'Pro' },
{ id: 'team', name: 'Team' }
]}
labelKey="name"
valueKey="id"
value={planIds}
onValueChange={({ newValue }) => setPlanIds(newValue)}
/>Select All
A "Select All" row is added at the top of the menu. selectAllText
changes its text (Select All by default) and hideSelectAllOption
removes it. It is also hidden automatically when there are fewer than
two options that can be selected, or when freeSolo is on. Its checkbox
is checked when every option is selected and indeterminate when only some
are, and clicking it again deselects everything.
Disabled options (see getOptionDisabled below) are left alone. Select All
adds every selectable option and keeps the disabled ones as they are, and
deselecting keeps only the disabled ones that were already selected.
They don't count towards the checkbox's checked or indeterminate state.
<MUIMultiAutocomplete
fieldName="skills"
options={['React', 'Vue', 'Angular', 'Svelte']}
value={skills}
onValueChange={({ newValue }) => setSkills(newValue)}
selectAllText="All skills"
/>Pass hideSelectAllOption to remove the row entirely.
Customizing individual options
renderOptionLabel customizes the label shown next to an option's checkbox.
It receives the option and a state object with selected, index, inputValue
and disabled, so the label can react to the option's status.
getOptionDisabled receives an option and returns true to disable it.
<MUIMultiAutocomplete
fieldName="plans"
options={[
{ id: 'free', name: 'Free', soldOut: false },
{ id: 'pro', name: 'Pro', soldOut: false },
{ id: 'team', name: 'Team', soldOut: true }
]}
labelKey="name"
valueKey="id"
value={plans}
onValueChange={({ newValue }) => setPlans(newValue)}
getOptionDisabled={option => option.soldOut}
renderOptionLabel={(option, { disabled }) => (
<span style={{ opacity: disabled ? 0.5 : 1 }}>
{option.name}{disabled ? ' (sold out)' : ''}
</span>
)}
/>Styling the checkboxes
checkboxProps is forwarded to every Checkbox, and formControlLabelProps
to every FormControlLabel that wraps it. The sx of formControlLabelProps
is merged with the default FormControlLabel styles from ConfigProvider.
<MUIMultiAutocomplete
fieldName="skills"
options={['React', 'Vue', 'Angular', 'Svelte']}
value={skills}
onValueChange={({ newValue }) => setSkills(newValue)}
checkboxProps={{ size: 'small', color: 'secondary' }}
formControlLabelProps={{ sx: { m: 0 } }}
/>Limiting the visible chips
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.
<MUIMultiAutocomplete
fieldName="skills"
options={['React', 'Vue', 'Angular', 'Svelte']}
value={skills}
onValueChange={({ newValue }) => setSkills(newValue)}
limitTags={3}
getLimitTagsText={hiddenCount => `+${hiddenCount} skills`}
ChipProps={{ color: 'primary', size: 'small' }}
/>Free text entry
freeSolo lets the user add a value that isn't in options. The typed
string is passed to onValueChange as it is, and shown as a chip.
autoSelect defaults to true with freeSolo, so text typed in the field
is committed when it loses focus. Pass autoSelect={false} to require Enter.
<MUIMultiAutocomplete
fieldName="tags"
options={['bug', 'feature', 'docs']}
value={tags}
onValueChange={({ newValue }) => setTags(newValue)}
freeSolo
/>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.
Clearing, loading and placeholder
A clear button is shown once there is a selection, and disableClearable
removes it. Set loading while the options are being fetched: a small
spinner appears at the end of the input (customize it with
circularProgressProps), and the popup shows the loading text instead
of "No options" when there are no options yet. autoHighlight is true
by default, which differs from Material UI, so the first option is
highlighted as the user types. A placeholder in textFieldProps is
shown only while nothing is selected.
<MUIMultiAutocomplete
fieldName="skills"
options={['React', 'Vue', 'Angular', 'Svelte']}
value={skills}
onValueChange={({ newValue }) => setSkills(newValue)}
loading={isFetchingSkills}
textFieldProps={{ placeholder: 'Pick your skills' }}
/>API
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* | 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. |
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). |
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 |
autoSelect | boolean | 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 |
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. |
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. |
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
Integrated with Formik — a checkbox multi-select
storing a string[] with selectAllText, limitTags and checkboxProps,
plus object options with getOptionDisabled.
Reference
Source Code
View the full implementation of this component on GitHub.