Skip to content
+

Select

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

  • Feedback
  • Bundle size
  • WAI-ARIA
Component demosComponents APIHooks 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

disabledRequired

Type:boolean


labelRequired

Type:string | React.ReactNode


valueRequired

Type:Value


id

Type:string


rootRef

Type:React.Ref<Element>


Return value

getRootProps

Resolver for the root slot's props.

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


highlighted

If true, the option is highlighted.

Type:boolean


index

Type:number


rootRef

Ref to the root slot DOM node.

Type:React.RefCallback<Element> | null


selected

If true, the option is selected.

Type:boolean



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


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

areOptionsEqual

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.

Type:(a: OptionValue, b: OptionValue) => boolean


buttonRef

The ref of the trigger button element.

Type:React.Ref<Element>


componentName

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

Type:string

Default:'useSelect'


defaultOpen

If true, the select will be open by default.

Type:boolean

Default:false


defaultValue

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

Type:SelectValue<OptionValue, Multiple>


disabled

If true, the select is disabled.

Type:boolean

Default:false


getOptionAsString

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.

Type:(option: SelectOption<OptionValue>) => string

Default:defaultOptionStringifier


getSerializedValue

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.

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


listboxId

The id attribute of the listbox element.

Type:string


listboxRef

The ref of the listbox element.

Type:React.Ref<Element>


multiple

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

Type:Multiple

Default:false


name

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.

Type:string


onChange

Callback fired when an option is selected.

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


onHighlightChange

Callback fired when an option is highlighted.

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


onOpenChange

Callback fired when the listbox is opened or closed.

Type:(open: boolean) => void


open

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

Type:boolean


options

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

Type:SelectOptionDefinition<OptionValue>[]


required

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

Type:boolean


value

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

Type:SelectValue<OptionValue, Multiple>


Return value

buttonActive

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

Type:boolean


buttonFocusVisible

If true, the trigger button has a visible focus.

Type:boolean


buttonRef

Ref to the button slot DOM node.

Type:React.RefCallback<Element> | null


contextValue

A value to be passed to the SelectProvider component.

Type:SelectProviderValue<Value>


disabled

If true, the select is disabled.

Type:boolean


dispatch

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

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


getButtonProps

Resolver for the button slot's props.

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


getHiddenInputProps

Resolver for the hidden input slot's props.

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


getListboxProps

Resolver for the listbox slot's props.

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


getOptionMetadata

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

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


highlightedOption

The value of the highlighted option.

Type:Value | null


listboxRef

Ref to the listbox slot DOM node.

Type:React.RefCallback<Element> | null


open

If true, the listbox is open.

Type:boolean


options

Values of all the registered options.

Type:Value[]


value

The value of the selected option(s).

Type:SelectValue<Value, Multiple>



Edit this page

Was this page helpful?


RatingSlider

•

Blog

•

Store