MUIMultiAutocompleteObject
MUIMultiAutocompleteObject is a multi-select
Autocomplete with checkboxes
and an optional "Select All" row that stores an array of complete option
objects.
Usage
import MUIMultiAutocompleteObject, {
MUIMultiAutocompleteObjectProps
} from '@nish1896/mui-components/mui/multi-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 [members, setMembers] = useState<User[]>([]);
<MUIMultiAutocompleteObject
fieldName="members"
options={users}
labelKey="name"
valueKey="id"
value={members}
onValueChange={({ newValue, selectedOption }) => setMembers(newValue)}
/>onValueChange receives { newValue, selectedOption }: the next array of
objects, and the option that triggered the change. selectedOption is
'__ALL__' when "Select All" is toggled. Clearing the field yields
newValue as [] and selectedOption as undefined.
Every option has a checkbox, and the menu stays open while the user picks.
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. 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. The Select
All option 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.
<MUIMultiAutocompleteObject
fieldName="skills"
options={skillOptions}
labelKey="name"
valueKey="id"
value={skills}
onValueChange={({ newValue }) => setSkills(newValue)}
selectAllText="All skills"
/>Pass hideSelectAllOption to remove the row entirely.
Disabled options and custom labels
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.
<MUIMultiAutocompleteObject
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.
<MUIMultiAutocompleteObject
fieldName="skills"
options={skillOptions}
labelKey="name"
valueKey="id"
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.
<MUIMultiAutocompleteObject
fieldName="skills"
options={skillOptions}
labelKey="name"
valueKey="id"
value={skills}
onValueChange={({ newValue }) => setSkills(newValue)}
limitTags={3}
getLimitTagsText={hiddenCount => `+${hiddenCount} skills`}
ChipProps={{ color: 'primary', size: 'small' }}
/>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.
<MUIMultiAutocompleteObject
fieldName="skills"
options={skillOptions}
labelKey="name"
valueKey="id"
value={skills}
onValueChange={({ newValue }) => setSkills(newValue)}
loading={isFetchingSkills}
textFieldProps={{ placeholder: 'Pick your skills' }}
/>API
labelKey and valueKey are required.
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[] | Currently selected option objects. 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 selected object array and the option that triggered the change (or the select-all sentinel). |
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. |
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
Driven by plain React state — a checkbox multi-select storing whole objects,
with a Select-All option, limitTags, ChipProps and a custom
renderOptionLabel.
Source Code
View the full implementation of this component on GitHub.