Select

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

Component demos Components API Hooks API

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

Name	Type	Default	Description
disabled*	boolean
label*	string \| React.ReactNode
value*	Value
id	string
rootRef	React.Ref<Element>

Return value

Name	Type	Description
getRootProps	<ExternalProps extends Record<string, unknown>>(externalProps?: ExternalProps) => UseOptionRootSlotProps<ExternalProps>	Resolver for the root slot's props.
highlighted	boolean	If `true`, the option is highlighted.
index	number
rootRef	React.RefCallback<Element> \| null	Ref to the root slot DOM node.
selected	boolean	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

Name	Type	Default	Description

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

Name	Type	Default	Description
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.
buttonRef	React.Ref<Element>		The ref of the trigger button element.
componentName	string	'useSelect'	The name of the component using useSelect. For debugging purposes.
defaultOpen	boolean	false	If `true`, the select will be open by default.
defaultValue	SelectValue<OptionValue, Multiple>		The default selected value. Use when the component is not controlled.
disabled	boolean	false	If `true`, the select is disabled.
getOptionAsString	(option: SelectOption<OptionValue>) => string	defaultOptionStringifier	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.
listboxId	string		The `id` attribute of the listbox element.
listboxRef	React.Ref<Element>		The ref of the listbox element.
multiple	Multiple	false	If `true`, the end user can select multiple values. This affects the type of the `value`, `defaultValue`, and `onChange` props.
name	string		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.
open	boolean		Controls the open state of the select's listbox. This is the controlled equivalent of the `defaultOpen` prop.
options	ReadonlyArray<SelectOptionDefinition<OptionValue>>		An alternative way to specify the options. If this parameter is set, options defined as JSX children are ignored.
required	boolean		If `true`, the select embedded in a form must have a selected value. Otherwise, the form submission will fail.
value	SelectValue<OptionValue, Multiple>		The selected value. Set to `null` to deselect all options.

Return value

Name	Type	Description
buttonActive	boolean	If `true`, the trigger button is active (pressed).
buttonFocusVisible	boolean	If `true`, the trigger button has a visible focus.
buttonRef	React.RefCallback<Element> \| null	Ref to the button slot DOM node.
contextValue	SelectProviderValue<Value>	A value to be passed to the `SelectProvider` component.
disabled	boolean	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.
highlightedOption	Value \| null	The value of the highlighted option.
listboxRef	React.RefCallback<Element> \| null	Ref to the listbox slot DOM node.
open	boolean	If `true`, the listbox is open.
options	Value[]	Values of all the registered options.
value	SelectValue<Value, Multiple>	The value of the selected option(s).