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.

Form submission

The Select component supports name and required props that will be used when submitting the form.

Variants

The Select component supports the four global variants: outlined (default), plain, soft, and solid.

The variant and color values are propagated to the Select's button and listbox slots.

To customize the variant and color for a specific slot, use slotProps:

<Select
  variant="plain"
  slotProps={{
    listbox: {
      variant: 'outlined',
    },
  }}
/>

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>
);

Multiple selections

Set the multiple prop to let your users select multiple options from the list. In contrast with single-selection mode, the options popup doesn't close after an item is selected, which enables users to continue choosing more options.

Note that in multiple selection mode, the value prop (and defaultValue) is an array.

Selected value appearance

Use the renderValue prop to customize the display of the selected options.

Form submission

The Select component supports name and required props that will be used when submitting the form.

Listbox

Maximum height

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

<Select
  slotProps={{
    listbox: {
      sx: {
        maxHeight: '300px',
      },
    },
  }}
>
  ...
</Select>

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.

Placement

To align listbox position to Select while displaying long options, use slotProps prop to position listbox slot:

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.

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
  slotProps={{
    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

Use the Base UI Select for complete ownership of the component's design, with no Material UI or Joy UI styles to override. This unstyled version of the component is the ideal choice for heavy customization with a smaller bundle size.

API

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

• <Option />
• <Select />