MUI Components
NPM

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.

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*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.
refRef<HTMLInputElement>
Forwarded ref for the underlying MUI TextField's input element — use it to imperatively focus the field or read its DOM node.
valueOption[]
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).
disableClearableboolean
When true, the selected value cannot be cleared from the input.
Default: 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.
selectAllTextstring
Text to display for the "Select All" option.
Default: 'Select All'
hideSelectAllOptionboolean
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.
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.
checkboxPropsCheckboxProps
CheckboxProps passed down to each Checkbox component — custom color, size, etc.
formControlLabelPropsFormControlLabelProps
FormControlLabelProps forwarded to the internal FormControlLabel. Multiple fields can be configured using the ConfigProvider component.
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.
formLabelPropsFormLabelProps
FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component.
hideLabelboolean
When true, hides the rendered field label while preserving accessible labeling where possible.
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

Driven by plain React state — a checkbox multi-select storing whole objects, with a Select-All option, limitTags, ChipProps and a custom renderOptionLabel.

Multi-select storing whole objects, with Select All

Website revamp
You'll get updates for the selected projects

Form State - Values & Errors

Source Code

View the full implementation of this component on GitHub.