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';

const [members, setMembers] = useState<User[]>([]);

<MUIMultiAutocompleteObject
  fieldName="members"
  value={members}
  onValueChange={({ newValue }) => setMembers(newValue)}
  options={users}
  labelKey="name"
  valueKey="id"
/>

Props#

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.
`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).
`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.
`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#

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

Multi Autocomplete

Checkbox