Select

Select components are used for collecting user provided information from a list of options.

Introduction

The Select component is used to trigger a popup that displays a list of Option components.

Component

After installation, you can start building with this component using the following basic elements:

<span class="token keyword">import</span> Select <span class="token keyword">from</span> <span class="token string">'@mui/joy/Select'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> Option <span class="token keyword">from</span> <span class="token string">'@mui/joy/Option'</span><span class="token punctuation">;</span>

<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">SelectBasic</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Select</span></span> <span class="token attr-name">defaultValue</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>dog<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
      <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Option</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>dog<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Dog<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Option</span></span><span class="token punctuation">></span></span>
      <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Option</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>cat<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Cat<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Option</span></span><span class="token punctuation">></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Select</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

Basic usage

The Select component is similar to the native HTML's <select> and <option> tags.

<Select defaultValue="dog" onChange={handleChange}>
  <Option value="dog">Dog</Option>
  <Option value="cat">Cat</Option>
  <Option value="fish">Fish</Option>
  <Option value="bird">Bird</Option>
</Select>

<Select defaultValue="dog" onChange={handleChange}>
  <Option value="dog">Dog</Option>
  <Option value="cat">Cat</Option>
  <Option value="fish">Fish</Option>
  <Option value="bird">Bird</Option>
</Select>

Press Enter to start editing

Decorators

Use the startDecorator and/or endDecorator props to add supporting icons or elements to the select.

<Select
  placeholder="Select a pet…"
  startDecorator={<FavoriteBorder />}
  endDecorator={
    <Chip size="sm" color="danger" variant="soft">
      +5
    </Chip>
  }
  sx={{ width: 240 }}
>
  <Option value="dog">Dog</Option>
  <Option value="cat">Cat</Option>
  <Option value="fish">Fish</Option>
  <Option value="bird">Bird</Option>
</Select>

<Select
  placeholder="Select a pet…"
  startDecorator={<FavoriteBorder />}
  endDecorator={
    <Chip size="sm" color="danger" variant="soft">
      +5
    </Chip>
  }
  sx={{ width: 240 }}
>
  <Option value="dog">Dog</Option>
  <Option value="cat">Cat</Option>
  <Option value="fish">Fish</Option>
  <Option value="bird">Bird</Option>
</Select>

Press Enter to start editing

If you have interactive elements as the select's decorators, call stopPropagation() from the mouse down event to prevent the popup from being opened.

<span class="token operator">&lt;</span>IconButton
  onMouseDown<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">(</span><span class="token parameter">event</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
    <span class="token comment">// don't open the popup when clicking on this button</span>
    event<span class="token punctuation">.</span><span class="token function">stopPropagation</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span><span class="token punctuation">}</span>
  onClick<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
    <span class="token comment">// click handler goes here</span>
  <span class="token punctuation">}</span>
<span class="token operator">></span><span class="token operator">...</span><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">IconButton</span></span><span class="token punctuation">></span></span>

Indicator

To change the default indicator, use the indicator prop with either any React element (including string) or null as value (to remove the indicator completely).

To apply the indicator to all instances of the select component, customize the indicator prop directly in the theme:

<span class="token keyword">import</span> <span class="token punctuation">{</span> extendTheme<span class="token punctuation">,</span> CssVarsProvider <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/joy/styles'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> Select <span class="token keyword">from</span> <span class="token string">'@mui/joy/Select'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">components</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">JoySelect</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">defaultProps</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">indicator</span><span class="token operator">:</span> <span class="token string">'↕'</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> <span class="token function-variable function">App</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">CssVarsProvider</span></span> <span class="token attr-name">theme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>theme<span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Select</span></span><span class="token punctuation">></span></span><span class="token operator">...</span>options<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Select</span></span><span class="token punctuation">></span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">CssVarsProvider</span></span><span class="token punctuation">></span></span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>

Listbox

Maximum height

To change the listbox's maximum height, use slotProps prop to target listbox slot:

<span class="token operator">&lt;</span>Select
  slotProps<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span>
    <span class="token literal-property property">listbox</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">sx</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">maxHeight</span><span class="token operator">:</span> <span class="token string">'300px'</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">}</span>
<span class="token operator">></span>
  <span class="token operator">...</span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Select</span></span><span class="token punctuation">></span></span>

Minimum width

By default, the listbox's width is equal to Select's button or the maximum content of its children. You can control the minimum width by using slotProps prop to target listbox slot.

Width is fixed at 100px

To control the placement of the listbox, use placement:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Select</span></span>
  <span class="token attr-name">slotProps</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span>
    <span class="token comment">// the left-edge of the listbox will align with button.</span>
    <span class="token literal-property property">listbox</span><span class="token operator">:</span> <span class="token punctuation">{</span> <span class="token literal-property property">placement</span><span class="token operator">:</span> <span class="token string">'bottom-start'</span> <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">}</span></span>
<span class="token punctuation">></span></span>

Controlling the open state

You can control the open state of the select with the listboxOpen prop. Alternatively, it is also possible to set the initial (uncontrolled) open state of the component with the defaultListboxOpen prop.

`Option` component

The Option component is used for the choosable options within the select.

The selected option inherits the color from the Select parent, and it uses the primary palette by default. However, it does not inherit the Select's used variant.

The ListItemButton component is very similar to this one, as they share the same internal styles. In fact, you can mix them together to compose various designs.

In the demo below, we're using the ListItemDecorator to provide space between the avatars. We're also using the ListDivider as a visual separator.

Grouped options

To create a listbox with grouped options, wrap the Option with List component and provide an associated label using ListItem. That way, you'll have a consistent height and will be able to leverage nested CSS variables.

If you'd like to set a max-height for a long list of options, make sure to specify it to the listbox slot so that keyboard-based navigation works as expected.

<span class="token operator">&lt;</span>Select
  slotProps<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span>
    <span class="token literal-property property">listbox</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">sx</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">maxHeight</span><span class="token operator">:</span> <span class="token number">300</span><span class="token punctuation">,</span>
        <span class="token literal-property property">overflow</span><span class="token operator">:</span> <span class="token string">'auto'</span><span class="token punctuation">,</span> <span class="token comment">// required for scrolling</span>
      <span class="token punctuation">}</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span><span class="token punctuation">}</span>
<span class="token operator">></span>

Accessibility

In order for the select to be accessible, it should be linked to a label.

The FormControl automatically generates a unique id that links the select with the FormLabel component:

Favorite pet

This is a helper text.

Alternatively, you can do it manually by targeting the button slot:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>label</span> <span class="token attr-name">htmlFor</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>select-button<span class="token punctuation">"</span></span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>select-label<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Label<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>label</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Select</span></span>
  <span class="token attr-name">slotProps</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span>
    <span class="token literal-property property">button</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">id</span><span class="token operator">:</span> <span class="token string">'select-button'</span><span class="token punctuation">,</span>
      <span class="token string-property property">'aria-labelledby'</span><span class="token operator">:</span> <span class="token string">'select-label select-button'</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span><span class="token punctuation">}</span></span>
<span class="token punctuation">></span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Option</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>option1<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Option <span class="token constant">I</span><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Option</span></span><span class="token punctuation">></span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Option</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>option2<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Option <span class="token constant">II</span><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Option</span></span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Select</span></span><span class="token punctuation">></span></span>

Common examples

Clear action

Use the IconButton component as a decorator to the Select to add a clear action.

The Select will set the focus-visible state back to the select button after the select value is cleared, ensuring a great keyboard-navigation experience.

Selected value appearance

The select will display the value of the label prop when the option is selected.

The value can be string, number, or any valid React element.

Debugging

To keep the listbox open for inspecting elements, enable the Emulate a focused page option from the Chrome DevTool Rendering tab. You can also access this option by using command menu and search for it.

Unstyled

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.