MUI Components
NPM

MUINativeSelect

MUINativeSelect wraps the Material UI Native Select — a real <select> element, ideal for mobile and lightweight dropdowns — with the same label/error/helper-text handling as the rest of the suite.

Usage

import MUINativeSelect, { MUINativeSelectProps } from '@nish1896/mui-components/mui/native-select';
const [country, setCountry] = useState();

<MUINativeSelect
  fieldName="country"
  options={['India', 'United States', 'Germany']}
  value={country}
  onValueChange={({ newValue, event }) => setCountry(newValue)}
/>

Only a single selection is supported, and undefined or null mean no selection. onValueChange receives { newValue, event }: the normalized value and the native change event. The control always fills the width of its container.

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.

const [country, setCountry] = useState();

<MUINativeSelect
  fieldName="country"
  options={[
    { code: 'AUS', country: 'Australia' },
    { code: 'IN', country: 'India' },
    { code: 'UAE', country: 'United Arab Emirates' }
  ]}
  labelKey="country"
  valueKey="code"
  value={country}
  onValueChange={({ newValue }) => setCountry(newValue)}
/>

Default option & placeholder

A native select always renders a first <option> with the value ''. Its text is defaultOptionText, falling back to placeholder, and it is empty when neither is set. The option is disabled when the field is required, so it can't be picked again once a real option is chosen. Picking it, when it is enabled, gives '' as the new value.

<MUINativeSelect
  fieldName="currency"
  options={['USD', 'EUR', 'GBP']}
  value={currency}
  onValueChange={({ newValue }) => setCurrency(newValue)}
  defaultOptionText="Select currency"
  required
/>

placeholder works as a shorthand for the same text. A native <select> has no placeholder of its own, so it only sets the default option's text.

Customizing individual options

renderOptionLabel customizes the text of each option. It also receives a { disabled, selected } state, which tells you whether the option is disabled or it has been selected. An <option> can only display text, so return a string or number, not elements.

getOptionDisabled receives an option and returns true to disable it.

<MUINativeSelect
  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)}
  getOptionDisabled={option => option.stock === 0}
  renderOptionLabel={(option, { disabled }) => (
    disabled ? `${option.name} (out of stock)` : `${option.name} (${option.stock} left)`
  )}
/>

Label placement

A native select has no inline label, so showLabelAboveFormField defaults to true and the label is rendered above the control. Pass false to hide the visible label while keeping the accessible name. The prop takes precedence over allLabelsAboveFields from the config, so false hides this label even when the config places every label above its field.

API

For object options, pass labelKey and valueKey.

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.
valuestring | number | null
Current select value, normalized with valueKey for object options.
onValueChange*({ newValue, event }) => void
Called after the selected value is normalized using valueKey for object options.
renderOptionLabel(option, state) => ReactNode
Custom renderer for the text of each <option>. Receives the option and a { disabled, selected } state. A native <option> can only display text, so return a string or number rather than elements. When not provided, the label comes from the option itself or the property named 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.
defaultOptionTextstring
Text of the default option, which is always rendered first with the value ''. Falls back to placeholder, and is empty when neither is set. The option is disabled when the field is required.
placeholderstring
Text of the default option when defaultOptionText is not set. A native <select> has no placeholder of its own, so this is only the default option's text.
labelReactNode
Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name".
showLabelAboveFormFieldboolean
Whether the field label renders above the component. Since it has no built-in inline label, the label renders above the component by default; pass false to hide the visible label (the accessible name is still applied). Takes precedence over allLabelsAboveFields from the ConfigProvider.
Default: true
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

Native select with renderOptionLabel & defaultOptionText

Native select with number options and getOptionDisabled

Form State - Values & Errors

Reference

Source Code

View the full implementation of this component on GitHub.