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:

import Select from '@mui/joy/Select';
import Option from '@mui/joy/Option';

export default function SelectBasic() {
  return (
    <Select defaultValue="dog">
      <Option value="dog">Dog</Option>
      <Option value="cat">Cat</Option>
    </Select>
  );
}

Basic usage

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

Decorators

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

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

<IconButton
  onMouseDown={(event) => {
    // don't open the popup when clicking on this button
    event.stopPropagation();
  }}
  onClick={() => {
    // click handler goes here
  }
>...</IconButton>

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:

import { extendTheme, CssVarsProvider } from '@mui/joy/styles';
import Select from '@mui/joy/Select';

const theme = extendTheme({
  components: {
    JoySelect: {
      defaultProps: {
        indicator: '↕',
      },
    },
  },
});

const App = () => (
  <CssVarsProvider theme={theme}>
    <Select>...options</Select>
  </CssVarsProvider>
);

Option component

The Option component is used for the chooseable 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.

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:

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

<label htmlFor="select-button" id="select-label">Label</label>
<Select
  componentsProps={{
    button: {
      id: 'select-button',
      'aria-labelledby': 'select-label select-button',
    }
  }}
>
  <Option value="option1">Option I</Option>
  <Option value="option2">Option II</Option>
</Select>

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

The component also comes with an unstyled version. It's ideal for doing heavy customizations and minimizing bundle size.