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

disabledRequired

Type:

boolean

labelRequired

Type:

string | React.ReactNode

valueRequired

Type:

Value

Type:

string

rootRef

Type:

React.Ref<Element>

Return value

getRootProps

Type:

<Other extends EventHandlers>(otherHandlers?: Other) => UseOptionRootSlotProps<Other>

highlighted

Type:

boolean

index

Type:

number

rootRef

Type:

React.RefCallback<Element> | null

selected

Type:

boolean

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>

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) => void

getButtonProps

Resolver for the button slot's props.

Type:

<OtherHandlers extends EventHandlers = {}>(otherHandlers?: OtherHandlers) => UseSelectButtonSlotProps<OtherHandlers>

getHiddenInputProps

Resolver for the hidden input slot's props.

Type:

<OtherHandlers extends EventHandlers = {}>(otherHandlers?: OtherHandlers) => UseSelectHiddenInputSlotProps<OtherHandlers>

getListboxProps

Resolver for the listbox slot's props.

Type:

<OtherHandlers extends EventHandlers = {}>(otherHandlers?: OtherHandlers) => UseSelectListboxSlotProps<OtherHandlers>

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>