Skip to content
+

Select

The Select components let you create lists of options for users to choose from.

useOption API

Import

import { useOption } from '@mui/base/useOption';
// or
import { useOption } from '@mui/base';
Learn about the difference by reading this guide on minimizing bundle size.

Parameters

NameTypeDescription
disabled*boolean
label*string | React.ReactNode
value*Value
idstring
rootRefReact.Ref<Element>

Return value

NameTypeDescription
getRootProps<ExternalProps extends Record<string, unknown>>(externalProps?: ExternalProps) => UseOptionRootSlotProps<ExternalProps>

Resolver for the root slot's props.

highlightedboolean

If true, the option is highlighted.

indexnumber
rootRefReact.RefCallback<Element> | null

Ref to the root slot DOM node.

selectedboolean

If true, the option is selected.


useOptionContextStabilizer API

Import

import { useOptionContextStabilizer } from '@mui/base/useOption';
// or
import { useOptionContextStabilizer } from '@mui/base';
Learn about the difference by reading this guide on minimizing bundle size.This hook does not accept any input parameters.

Return value

NameTypeDescription

useSelect API

Import

import { useSelect } from '@mui/base/useSelect';
// or
import { useSelect } from '@mui/base';
Learn about the difference by reading this guide on minimizing bundle size.

Parameters

NameTypeDefaultDescription
areOptionsEqual(a: OptionValue, b: OptionValue) => boolean-

A function used to determine if two options' values are equal. By default, reference equality is used.
There is a performance impact when using the areOptionsEqual prop (proportional to the number of options). Therefore, it's recommented to use the default reference equality comparison whenever possible.

buttonRefReact.Ref<Element>-

The ref of the trigger button element.

componentNamestring'useSelect'

The name of the component using useSelect. For debugging purposes.

defaultOpenbooleanfalse

If true, the select will be open by default.

defaultValueSelectValue<OptionValue, Multiple>-

The default selected value. Use when the component is not controlled.

disabledbooleanfalse

If true, the select is disabled.

getOptionAsString(option: SelectOption<OptionValue>) => stringdefaultOptionStringifier

A function used to convert the option label to a string. This is useful when labels are elements and need to be converted to plain text to enable keyboard navigation with character keys.

getSerializedValue(option: SelectValue<SelectOption<OptionValue>, Multiple>) => React.InputHTMLAttributes<HTMLInputElement>['value']-

A function to convert the currently selected value to a string. Used to set a value of a hidden input associated with the select, so that the selected value can be posted with a form.

listboxIdstring-

The id attribute of the listbox element.

listboxRefReact.Ref<Element>-

The ref of the listbox element.

multipleMultiplefalse

If true, the end user can select multiple values. This affects the type of the value, defaultValue, and onChange props.

namestring-

The name attribute of the hidden input element. This is useful when the select is embedded in a form and you want to access the selected value in the form data.

onChange(event: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null, value: SelectValue<OptionValue, Multiple>) => void-

Callback fired when an option is selected.

onHighlightChange(event: React.MouseEvent<Element, MouseEvent> | React.KeyboardEvent<Element> | React.FocusEvent<Element, Element> | null, highlighted: OptionValue | null) => void-

Callback fired when an option is highlighted.

onOpenChange(open: boolean) => void-

Callback fired when the listbox is opened or closed.

openboolean-

Controls the open state of the select's listbox. This is the controlled equivalent of the defaultOpen prop.

optionsReadonlyArray<SelectOptionDefinition<OptionValue>>-

An alternative way to specify the options. If this parameter is set, options defined as JSX children are ignored.

requiredboolean-

If true, the select embedded in a form must have a selected value. Otherwise, the form submission will fail.

valueSelectValue<OptionValue, Multiple>-

The selected value. Set to null to deselect all options.

Return value

NameTypeDescription
buttonActiveboolean

If true, the trigger button is active (pressed).

buttonFocusVisibleboolean

If true, the trigger button has a visible focus.

buttonRefReact.RefCallback<Element> | null

Ref to the button slot DOM node.

contextValueSelectProviderValue<Value>

A value to be passed to the SelectProvider component.

disabledboolean

If true, the select is disabled.

dispatch(action: ListAction<Value> | SelectAction<Value>) => void

Action dispatcher for the select component. Allows to programmatically control the select.

getButtonProps<ExternalProps extends Record<string, unknown> = {}>(externalProps?: ExternalProps) => UseSelectButtonSlotProps<ExternalProps>

Resolver for the button slot's props.

getHiddenInputProps<ExternalProps extends Record<string, unknown> = {}>(externalProps?: ExternalProps) => UseSelectHiddenInputSlotProps<ExternalProps>

Resolver for the hidden input slot's props.

getListboxProps<ExternalProps extends Record<string, unknown> = {}>(externalProps?: ExternalProps) => UseSelectListboxSlotProps<ExternalProps>

Resolver for the listbox slot's props.

getOptionMetadata(optionValue: Value) => SelectOption<Value> | undefined

A function that returns the metadata of an option with a given value.

highlightedOptionValue | null

The value of the highlighted option.

listboxRefReact.RefCallback<Element> | null

Ref to the listbox slot DOM node.

openboolean

If true, the listbox is open.

optionsValue[]

Values of all the registered options.

valueSelectValue<Value, Multiple>

The value of the selected option(s).