MUI Components
NPM

MUISelect

MUISelect wraps the Material UI Select with label, error and helper-text handling. It supports single or multiple selection and either primitive or object options via labelKey/valueKey.

Tip

If the number of options exceeds 20, consider using MUIAutocomplete or MUIMultiAutocomplete for better searchability, improved keyboard navigation, and overall performance.

Usage

import MUISelect, { MUISelectProps } from '@nish1896/mui-components/mui/select';
const [role, setRole] = useState();

<MUISelect
  fieldName="role"
  options={['Admin', 'Editor', 'Viewer']}
  value={role}
  onValueChange={({ newValue, event, child }) => setRole(newValue)}
/>

With primitive options, the selected value has the same type as the options, so a string option gives a string and a number option gives a number. onValueChange receives { newValue, event, child }: the normalized value, the Material UI change event, and the selected option element.

undefined, null and '' all mean no selection.

Selecting multiple values

To select more than one option, set the multiple prop to true. value and newValue then become arrays, in the order the options were selected. The values keep the type of the options, so string options give a string[] and number options give a number[].

undefined, null and [] all mean no selection. An empty string is not a valid value for multiple.

const roles = ['Admin', 'Editor', 'Viewer'];
const [selectedRoles, setSelectedRoles] = useState<string[]>([]);

<MUISelect
  fieldName="roles"
  options={roles}
  value={selectedRoles}
  onValueChange={({ newValue }) => setSelectedRoles(newValue)}
  multiple
/>

The closed field shows the labels of the selected options joined with , . Use renderValue to display it differently, as described in Custom selected value section. Object options work the same way, and value is then an array of their valueKey properties.

With an array of objects

When options is an array of objects, both labelKey and valueKey are required.

  • labelKey: the property used as each option's visible label.
  • valueKey: the property used as each option's value.

The selected value has the type of the valueKey property: a string property gives a string, and a number property gives a number.

For example:

<MUISelect
  fieldName="country"
  options={[
    { code: 'AUS', country: 'Australia' },
    { code: 'IN', country: 'India' },
    { code: 'UAE', country: 'United Arab Emirates' },
  ]}
  labelKey="country"
  valueKey="code"
  multiple
/>

Default option & placeholder

Two props help when nothing is selected yet. showDefaultOption adds a first menu item with the value '', labelled with defaultOptionText, which defaults to "Select" followed by the label generated from fieldName, such as Select Role. Choosing it clears the selection. It is disabled when the field is required, so it can't be picked once a real option is chosen.

placeholder is text shown inside the closed field while nothing is selected. Unlike the default option it isn't a menu item, it is shown faded, and the inline label is not rendered while it is shown.

<MUISelect
  fieldName="role"
  options={['Admin', 'Editor', 'Viewer']}
  value={role}
  onValueChange={({ newValue }) => setRole(newValue)}
  showDefaultOption
  defaultOptionText="No role"
/>

<MUISelect
  fieldName="plan"
  options={['Free', 'Pro', 'Team']}
  value={plan}
  onValueChange={({ newValue }) => setPlan(newValue)}
  placeholder="Choose a plan"
/>

Customizing individual options

renderOptionLabel replaces the content of each menu item. It receives the option and a state object with disabled and selected, so the label can react to either.

getOptionDisabled receives an option and returns true to disable it.

<MUISelect
  fieldName="product"
  options={[
    { id: 1, name: 'Keyboard', stock: 12 },
    { id: 2, name: 'Monitor', stock: 0 },
    { id: 3, name: 'Mouse', stock: 4 }
  ]}
  labelKey="name"
  valueKey="id"
  value={product}
  onValueChange={({ newValue }) => setProduct(newValue)}
  renderOptionLabel={(option, { disabled, selected }) => (
    <span
      style={{
        opacity: disabled ? 0.5 : 1,
        fontWeight: selected ? 700 : 400
      }}
    >
      {option.name} ({option.stock} in stock)
    </span>
  )}
  getOptionDisabled={option => option.stock === 0}
/>

Custom selected value

renderValue changes what the closed field displays, while renderOptionLabel only changes the menu items. It receives the normalized value, which is an array when multiple is set. By default the selected option's label is shown, and the labels are joined with , for multiple selection.

<MUISelect
  fieldName="tags"
  options={['Bug', 'Feature', 'Docs', 'Chore']}
  value={tags}
  onValueChange={({ newValue }) => setTags(newValue)}
  multiple
  renderValue={selected => (
    selected.length ? `${selected.length} selected` : ''
  )}
/>

Styling the options

menuItemProps is forwarded to every MenuItem, including the default option, which is handy for a shared dense, divider or sx. inputLabelProps is forwarded to the InputLabel shown inside the field's outline. It has no effect when the field uses a label above (showLabelAboveFormField), hideLabel, or a placeholder with no value selected.

<MUISelect
  fieldName="role"
  options={['Admin', 'Editor', 'Viewer']}
  value={role}
  onValueChange={({ newValue }) => setRole(newValue)}
  menuItemProps={{ dense: true, sx: { fontSize: 14 } }}
  inputLabelProps={{ sx: { fontWeight: 600 } }}
/>

API

MUISelectProps also accepts the remaining SelectProps.

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*string[] | number[] | object[]
An array with string, numeric or object values. Make sure to pass labelKey and valueKey when options is an array of objects.
labelKeystring
Property name used as the visible label for each option. Required when options is an array of objects.
valueKeystring
Property name used to derive the exposed value for each option. Required when options is an array of objects.
multipleboolean
When true, allows selecting multiple values.
valuestring | number | (string | number)[] | null
Current select value, normalized with valueKey for object options. Pass an array when multiple is true.
onValueChange*({ newValue, event, child }) => void
Called after the selected value is normalized using valueKey for object options. child is the selected option element provided by MUI Select.
renderValue(value) => ReactNode
Custom renderer for the selected value shown in the closed field. Unlike renderOptionLabel, which only affects the menu items, this changes what the field itself displays. Receives the normalized value, as an array when multiple. By default the selected option label is shown, and the labels are joined with , for multiple.
menuItemPropsMenuItemProps
MenuItemProps forwarded to every rendered option's MenuItem — custom dense, divider, sx, etc. key, value, disabled and children are controlled by the component.
Added in v2.
renderOptionLabel(option) => ReactNode
Custom renderer for option labels. When not provided, the label is derived from the option value or the property specified by labelKey.
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.
showDefaultOptionboolean
When true, displays a default placeholder option at the top of the dropdown menu. The option uses an empty string as its value and is automatically disabled when the field is required.
Default: false
defaultOptionTextstring
Custom text displayed for the default option when showDefaultOption is enabled.
Default: Select ${fieldLabel}
placeholderstring
Placeholder text displayed in the select input itself when no option is selected (not rendered as a selectable menu item).
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.
inputLabelPropsInputLabelProps
InputLabelProps forwarded to the internal InputLabel — the inline label shown inside the field's outline. id, htmlFor, shrink, disabled and children are controlled by the component.
Added in v2.
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

Single select field with helpertext and renderOptionLabel

Select an option to change selected text color from Orange

Multi-select with customIds

Multiple Select with options as an array of objects, with custom render function, customOnChange and disabled options

Select one or more teams

Select with number options and menuItemProps

Select a random number

Form State - Values & Errors

Reference

Source Code

View the full implementation of this component on GitHub.