--- productId: material-ui title: React Select component components: Select, NativeSelect githubLabel: 'scope: select' materialDesign: https://m2.material.io/components/menus#exposed-dropdown-menu waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/ githubSource: packages/mui-material/src/Select --- # Select Select components are used for collecting user provided information from a list of options. ## Basic select Menus are positioned under their emitting elements, unless they are close to the bottom of the viewport. ```tsx import * as React from 'react'; import Box from '@mui/material/Box'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import FormControl from '@mui/material/FormControl'; import Select, { SelectChangeEvent } from '@mui/material/Select'; export default function BasicSelect() { const [age, setAge] = React.useState(''); const handleChange = (event: SelectChangeEvent) => { setAge(event.target.value as string); }; return ( Age ); } ``` ## Advanced features The Select component is meant to be interchangeable with a native `` element of the [InputBase](/material-ui/api/input-base/). It extends the [text field components](/material-ui/react-text-field/) subcomponents, either the [OutlinedInput](/material-ui/api/outlined-input/), [Input](/material-ui/api/input/), or [FilledInput](/material-ui/api/filled-input/), depending on the variant selected. It shares the same styles and many of the same props. Refer to the respective component's API page for details. :::warning Unlike input components, the `placeholder` prop is not available in Select. To add a placeholder, refer to the [placeholder](#placeholder) section below. ::: ### Variants ```tsx import * as React from 'react'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import FormControl from '@mui/material/FormControl'; import Select, { SelectChangeEvent } from '@mui/material/Select'; export default function SelectVariants() { const [age, setAge] = React.useState(''); const handleChange = (event: SelectChangeEvent) => { setAge(event.target.value); }; return (
Age Age Age
); } ``` :::warning Note that when using FormControl with the outlined variant of the Select, you need to provide a label in two places: in the InputLabel component and in the `label` prop of the Select component (see the above demo). This is needed for the label floating animation to work correctly. ::: ### Labels and helper text Select always needs an accessible name. This can come from an associated visible label, such as an `InputLabel` linked to the `Select` with `labelId` or from adding an `aria-label` prop to the input element props (`inputProps`). If more information is needed, provide a helper text element and link it to the `Select` using `aria-describedby`. ```tsx import * as React from 'react'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import FormHelperText from '@mui/material/FormHelperText'; import FormControl from '@mui/material/FormControl'; import Select, { SelectChangeEvent } from '@mui/material/Select'; export default function SelectLabels() { const id = React.useId(); const noLabelId = React.useId(); const [age, setAge] = React.useState(''); const handleChange = (event: SelectChangeEvent) => { setAge(event.target.value); }; return (
Age Visible label and helper text aria-label and helper text
); } ``` ### Auto width ```tsx import * as React from 'react'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import FormControl from '@mui/material/FormControl'; import Select, { SelectChangeEvent } from '@mui/material/Select'; export default function SelectAutoWidth() { const [age, setAge] = React.useState(''); const handleChange = (event: SelectChangeEvent) => { setAge(event.target.value); }; return (
Age
); } ``` ### Small Size ```tsx import * as React from 'react'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import FormControl from '@mui/material/FormControl'; import Select, { SelectChangeEvent } from '@mui/material/Select'; export default function SelectSmall() { const [age, setAge] = React.useState(''); const handleChange = (event: SelectChangeEvent) => { setAge(event.target.value); }; return ( Age ); } ``` ### Other props ```tsx import * as React from 'react'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import FormHelperText from '@mui/material/FormHelperText'; import FormControl from '@mui/material/FormControl'; import Select, { SelectChangeEvent } from '@mui/material/Select'; export default function SelectOtherProps() { const [age, setAge] = React.useState(''); const handleChange = (event: SelectChangeEvent) => { setAge(event.target.value); }; return (
Age Disabled Age Error Age Read only Age Required
); } ``` ## Native select As the user experience can be improved on mobile using the native select of the platform, we allow such pattern. ```tsx import * as React from 'react'; import Box from '@mui/material/Box'; import InputLabel from '@mui/material/InputLabel'; import FormControl from '@mui/material/FormControl'; import NativeSelect from '@mui/material/NativeSelect'; export default function NativeSelectDemo() { const id = React.useId(); return ( Age ); } ``` ## TextField The `TextField` wrapper component is a complete form control including a label, input and help text. You can find an example with the select mode [in this section](/material-ui/react-text-field/#select). ## Customization Here are some examples of customizing the component. You can learn more about this in the [overrides documentation page](/material-ui/customization/how-to-customize/). The first step is to style the `InputBase` component. Once it's styled, you can either use it directly as a text field or provide it to the select `input` prop to have a `select` field. Notice that the `"standard"` variant is easier to customize, since it does not wrap the contents in a `fieldset`/`legend` markup. ```tsx import * as React from 'react'; import { styled } from '@mui/material/styles'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import FormControl from '@mui/material/FormControl'; import Select from '@mui/material/Select'; import NativeSelect from '@mui/material/NativeSelect'; import InputBase from '@mui/material/InputBase'; const BootstrapInput = styled(InputBase)(({ theme }) => ({ 'label + &': { marginTop: theme.spacing(3), }, '& .MuiInputBase-input': { borderRadius: 4, position: 'relative', backgroundColor: (theme.vars ?? theme).palette.background.paper, border: '1px solid #ced4da', fontSize: 16, padding: '10px 26px 10px 12px', transition: theme.transitions.create(['border-color', 'box-shadow']), // Use the system font instead of the default Roboto font. fontFamily: [ '-apple-system', 'BlinkMacSystemFont', '"Segoe UI"', 'Roboto', '"Helvetica Neue"', 'Arial', 'sans-serif', '"Apple Color Emoji"', '"Segoe UI Emoji"', '"Segoe UI Symbol"', ].join(','), '&:focus': { borderRadius: 4, borderColor: '#80bdff', boxShadow: '0 0 0 0.2rem rgba(0,123,255,.25)', }, }, })); export default function CustomizedSelects() { const textboxId = React.useId(); const selectId = React.useId(); const nativeId = React.useId(); const [age, setAge] = React.useState(''); const handleChange = (event: { target: { value: string } }) => { setAge(event.target.value); }; return (
Age Age Age } >
); } ``` 🎨 If you are looking for inspiration, you can check [MUI Treasury's customization examples](https://mui-treasury.com/primitive/select). ## Multiple select The `Select` component can handle multiple selections. It's enabled with the `multiple` prop. Like with the single selection, you can pull out the new value by accessing `event.target.value` in the `onChange` callback. It's always an array. ### Default ```tsx import * as React from 'react'; import { Theme, useTheme } from '@mui/material/styles'; import OutlinedInput from '@mui/material/OutlinedInput'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import FormControl from '@mui/material/FormControl'; import Select, { SelectChangeEvent } from '@mui/material/Select'; const ITEM_HEIGHT = 48; const ITEM_PADDING_TOP = 8; const MenuProps = { slotProps: { paper: { style: { maxHeight: ITEM_HEIGHT * 4.5 + ITEM_PADDING_TOP, width: 250, }, }, }, }; const names = [ 'Oliver Hansen', 'Van Henry', 'April Tucker', 'Ralph Hubbard', 'Omar Alexander', 'Carlos Abbott', 'Miriam Wagner', 'Bradley Wilkerson', 'Virginia Andrews', 'Kelly Snyder', ]; function getStyles(name: string, personName: string[], theme: Theme) { return { fontWeight: personName.includes(name) ? theme.typography.fontWeightMedium : theme.typography.fontWeightRegular, }; } export default function MultipleSelect() { const theme = useTheme(); const [personName, setPersonName] = React.useState([]); const handleChange = (event: SelectChangeEvent) => { const { target: { value }, } = event; setPersonName( // On autofill we get a stringified value. typeof value === 'string' ? value.split(',') : value, ); }; return (
Name
); } ``` ### Selection indicators This example demonstrates how icons are used to indicate the selection state of each item in the listbox. ```tsx import * as React from 'react'; import OutlinedInput from '@mui/material/OutlinedInput'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import FormControl from '@mui/material/FormControl'; import ListItemText from '@mui/material/ListItemText'; import Select, { SelectChangeEvent } from '@mui/material/Select'; import CheckBoxOutlineBlankIcon from '@mui/icons-material/CheckBoxOutlineBlank'; import CheckBoxIcon from '@mui/icons-material/CheckBox'; const ITEM_HEIGHT = 48; const ITEM_PADDING_TOP = 8; const MenuProps = { slotProps: { paper: { style: { maxHeight: ITEM_HEIGHT * 4.5 + ITEM_PADDING_TOP, width: 250, }, }, }, }; const names = [ 'Oliver Hansen', 'Van Henry', 'April Tucker', 'Ralph Hubbard', 'Omar Alexander', 'Carlos Abbott', 'Miriam Wagner', 'Bradley Wilkerson', 'Virginia Andrews', 'Kelly Snyder', ]; export default function MultipleSelectCheckmarks() { const [personName, setPersonName] = React.useState([]); const handleChange = (event: SelectChangeEvent) => { const { target: { value }, } = event; setPersonName( // On autofill we get a stringified value. typeof value === 'string' ? value.split(',') : value, ); }; return (
Tag
); } ``` ### Chip ```tsx import * as React from 'react'; import { Theme, useTheme } from '@mui/material/styles'; import Box from '@mui/material/Box'; import OutlinedInput from '@mui/material/OutlinedInput'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import FormControl from '@mui/material/FormControl'; import Select, { SelectChangeEvent } from '@mui/material/Select'; import Chip from '@mui/material/Chip'; const ITEM_HEIGHT = 48; const ITEM_PADDING_TOP = 8; const MenuProps = { slotProps: { paper: { style: { maxHeight: ITEM_HEIGHT * 4.5 + ITEM_PADDING_TOP, width: 250, }, }, }, }; const names = [ 'Oliver Hansen', 'Van Henry', 'April Tucker', 'Ralph Hubbard', 'Omar Alexander', 'Carlos Abbott', 'Miriam Wagner', 'Bradley Wilkerson', 'Virginia Andrews', 'Kelly Snyder', ]; function getStyles(name: string, personName: readonly string[], theme: Theme) { return { fontWeight: personName.includes(name) ? theme.typography.fontWeightMedium : theme.typography.fontWeightRegular, }; } export default function MultipleSelectChip() { const theme = useTheme(); const [personName, setPersonName] = React.useState([]); const handleChange = (event: SelectChangeEvent) => { const { target: { value }, } = event; setPersonName( // On autofill we get a stringified value. typeof value === 'string' ? value.split(',') : value, ); }; return (
Chip
); } ``` ### Placeholder ```tsx import * as React from 'react'; import { Theme, useTheme } from '@mui/material/styles'; import OutlinedInput from '@mui/material/OutlinedInput'; import MenuItem from '@mui/material/MenuItem'; import FormControl from '@mui/material/FormControl'; import Select, { SelectChangeEvent } from '@mui/material/Select'; const ITEM_HEIGHT = 48; const ITEM_PADDING_TOP = 8; const MenuProps = { slotProps: { paper: { style: { maxHeight: ITEM_HEIGHT * 4.5 + ITEM_PADDING_TOP, width: 250, }, }, }, }; const names = [ 'Oliver Hansen', 'Van Henry', 'April Tucker', 'Ralph Hubbard', 'Omar Alexander', 'Carlos Abbott', 'Miriam Wagner', 'Bradley Wilkerson', 'Virginia Andrews', 'Kelly Snyder', ]; function getStyles(name: string, personName: readonly string[], theme: Theme) { return { fontWeight: personName.includes(name) ? theme.typography.fontWeightMedium : theme.typography.fontWeightRegular, }; } export default function MultipleSelectPlaceholder() { const theme = useTheme(); const [personName, setPersonName] = React.useState([]); const handleChange = (event: SelectChangeEvent) => { const { target: { value }, } = event; setPersonName( // On autofill we get a stringified value. typeof value === 'string' ? value.split(',') : value, ); }; return (
); } ``` ### Native ```tsx import * as React from 'react'; import InputLabel from '@mui/material/InputLabel'; import FormControl from '@mui/material/FormControl'; import Select from '@mui/material/Select'; const names = [ 'Oliver Hansen', 'Van Henry', 'April Tucker', 'Ralph Hubbard', 'Omar Alexander', 'Carlos Abbott', 'Miriam Wagner', 'Bradley Wilkerson', 'Virginia Andrews', 'Kelly Snyder', ]; export default function MultipleSelectNative() { const id = React.useId(); const [personName, setPersonName] = React.useState([]); const handleChangeMultiple = (event: React.ChangeEvent) => { const { options } = event.target; const value: string[] = []; for (let i = 0, l = options.length; i < l; i += 1) { if (options[i].selected) { value.push(options[i].value); } } setPersonName(value); }; return (
Native multiple native value={personName} // @ts-ignore Typings are not considering `native` onChange={handleChangeMultiple} label="Native" inputProps={{ id: `${id}-select`, }} > {names.map((name) => ( ))}
); } ``` ## Controlling the open state You can control the open state of the select with the `open` prop. Alternatively, it is also possible to set the initial (uncontrolled) open state of the component with the `defaultOpen` prop. :::info - A component is **controlled** when it's managed by its parent using props. - A component is **uncontrolled** when it's managed by its own local state. Learn more about controlled and uncontrolled components in the [React documentation](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components). ::: ```tsx import * as React from 'react'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import FormControl from '@mui/material/FormControl'; import Select, { SelectChangeEvent } from '@mui/material/Select'; import Button from '@mui/material/Button'; export default function ControlledOpenSelect() { const [age, setAge] = React.useState(''); const [open, setOpen] = React.useState(false); const handleChange = (event: SelectChangeEvent) => { setAge(event.target.value); }; const handleClose = () => { setOpen(false); }; const handleOpen = () => { setOpen(true); }; return (
Age
); } ``` ## With a dialog While it's discouraged by the Material Design guidelines, you can use a select inside a dialog. ```tsx import * as React from 'react'; import Box from '@mui/material/Box'; import Button from '@mui/material/Button'; import Dialog from '@mui/material/Dialog'; import DialogActions from '@mui/material/DialogActions'; import DialogContent from '@mui/material/DialogContent'; import DialogTitle from '@mui/material/DialogTitle'; import InputLabel from '@mui/material/InputLabel'; import OutlinedInput from '@mui/material/OutlinedInput'; import MenuItem from '@mui/material/MenuItem'; import FormControl from '@mui/material/FormControl'; import Select, { SelectChangeEvent } from '@mui/material/Select'; export default function DialogSelect() { const nativeId = React.useId(); const selectId = React.useId(); const [open, setOpen] = React.useState(false); const [age, setAge] = React.useState(''); const handleChange = (event: SelectChangeEvent) => { setAge(Number(event.target.value) || ''); }; const handleClickOpen = () => { setOpen(true); }; const handleDialogClose = ( _event: React.SyntheticEvent, reason: string, ) => { if (!['backdropClick', 'escapeKeyDown'].includes(reason)) { setOpen(false); } }; const handleActionButtonClick = () => { setOpen(false); }; return (
Fill the form Age Age
); } ``` ## Grouping Display categories with the `ListSubheader` component or the native `` element. ```tsx import * as React from 'react'; import InputLabel from '@mui/material/InputLabel'; import MenuItem from '@mui/material/MenuItem'; import ListSubheader from '@mui/material/ListSubheader'; import FormControl from '@mui/material/FormControl'; import Select from '@mui/material/Select'; export default function GroupedSelect() { const nativeId = React.useId(); const id = React.useId(); return (
Grouping Grouping
); } ``` ## Accessibility To properly label your `Select` input you need an extra element with an `id` that contains a label. That `id` needs to match the `labelId` of the `Select`, for example: ```jsx Age ``` Alternatively a `TextField` with an `id` and `label` creates the proper markup and ids for you: ```jsx Ten Twenty ``` For a [native select](#native-select), you should mention a label by giving the value of the `id` attribute of the select element to the `InputLabel`'s `htmlFor` attribute: ```jsx Age ``` # NativeSelect API ## Demos For examples and details on the usage of this React component, visit the component demo pages: - [Select](https://mui.com/material-ui/react-select/) ## Import ```jsx import NativeSelect from '@mui/material/NativeSelect'; // or import { NativeSelect } from '@mui/material'; ``` ## Props | Name | Type | Default | Required | Description | |------|------|---------|----------|-------------| | children | `node` | - | No | | | classes | `object` | `{}` | No | Override or extend the styles applied to the component. | | IconComponent | `elementType` | `ArrowDropDownIcon` | No | | | input | `element` | `` | No | | | inputProps | `object` | - | No | | | onChange | `function(event: React.ChangeEvent) => void` | - | No | | | sx | `Array \| func \| object` | - | No | The system prop that allows defining system overrides as well as additional CSS styles. | | value | `any` | - | No | | | variant | `'filled' \| 'outlined' \| 'standard'` | - | No | | > **Note**: The `ref` is forwarded to the root element (HTMLDivElement). > Any other props supplied will be provided to the root element ([Input](https://mui.com/material-ui/api/input/)). ## Inheritance While not explicitly documented above, the props of the [Input](https://mui.com/material-ui/api/input/) component are also available on NativeSelect. ## Theme default props You can use `MuiNativeSelect` to change the default props of this component with the theme. ## CSS ### Rule name | Global class | Rule name | Description | |--------------|-----------|-------------| | `.Mui-disabled` | - | State class applied to the select component `disabled` class. | | `.Mui-error` | - | State class applied to the select component `error` class. | | - | filled | Styles applied to the select component if `variant="filled"`. | | - | icon | Styles applied to the icon component. | | - | iconFilled | Styles applied to the icon component if `variant="filled"`. | | - | iconOpen | Styles applied to the icon component if the popup is open. | | - | iconOutlined | Styles applied to the icon component if `variant="outlined"`. | | - | iconStandard | Styles applied to the icon component if `variant="standard"`. | | - | multiple | Styles applied to the select component if `multiple={true}`. | | - | nativeInput | Styles applied to the underlying native input component. | | - | outlined | Styles applied to the select component if `variant="outlined"`. | | - | root | Styles applied to the root element. | | - | select | Styles applied to the select component `select` class. | | - | standard | Styles applied to the select component if `variant="standard"`. | ## Source code If you did not find the information on this page, consider having a look at the implementation of the component for more detail. - [/packages/mui-material/src/NativeSelect/NativeSelect.js](https://github.com/mui/material-ui/tree/HEAD/packages/mui-material/src/NativeSelect/NativeSelect.js) # Select API ## Demos For examples and details on the usage of this React component, visit the component demo pages: - [Select](https://mui.com/material-ui/react-select/) ## Import ```jsx import Select from '@mui/material/Select'; // or import { Select } from '@mui/material'; ``` ## Props | Name | Type | Default | Required | Description | |------|------|---------|----------|-------------| | autoWidth | `bool` | `false` | No | | | children | `node` | - | No | | | classes | `object` | `{}` | No | Override or extend the styles applied to the component. | | defaultOpen | `bool` | `false` | No | | | defaultValue | `any` | - | No | | | displayEmpty | `bool` | `false` | No | | | IconComponent | `elementType` | `ArrowDropDownIcon` | No | | | id | `string` | - | No | | | input | `element` | - | No | | | inputProps | `object` | - | No | | | label | `node` | - | No | | | labelId | `string` | - | No | | | MenuProps | `object` | - | No | | | multiple | `bool` | `false` | No | | | native | `bool` | `false` | No | | | onChange | `function(event: SelectChangeEvent, child?: object) => void` | - | No | | | onClose | `function(event: object) => void` | - | No | | | onOpen | `function(event: object) => void` | - | No | | | open | `bool` | - | No | | | renderValue | `function(value: any) => ReactNode` | - | No | | | SelectDisplayProps | `object` | - | No | | | sx | `Array \| func \| object` | - | No | The system prop that allows defining system overrides as well as additional CSS styles. | | value | `'' \| any` | - | No | | | variant | `'filled' \| 'outlined' \| 'standard'` | `'outlined'` | No | | > **Note**: The `ref` is forwarded to the root element (HTMLDivElement). > Any other props supplied will be provided to the root element ([OutlinedInput](https://mui.com/material-ui/api/outlined-input/)). ## Inheritance While not explicitly documented above, the props of the [OutlinedInput](https://mui.com/material-ui/api/outlined-input/) component are also available on Select. ## Theme default props You can use `MuiSelect` to change the default props of this component with the theme. ## CSS ### Rule name | Global class | Rule name | Description | |--------------|-----------|-------------| | `.Mui-disabled` | - | State class applied to the select component `disabled` class. | | `.Mui-error` | - | State class applied to the root element if `error={true}`. | | - | filled | Styles applied to the select component if `variant="filled"`. | | `.Mui-focused` | - | Styles applied to the select component if it is focused. | | - | icon | Styles applied to the icon component. | | - | iconOpen | Styles applied to the icon component if the popup is open. | | - | multiple | Styles applied to the select component if `multiple={true}`. | | - | nativeInput | Styles applied to the underlying native input component. | | - | outlined | Styles applied to the select component if `variant="outlined"`. | | - | root | Styles applied to the root element. | | - | select | Styles applied to the select component `select` class. | | - | standard | Styles applied to the select component if `variant="standard"`. | ## Source code If you did not find the information on this page, consider having a look at the implementation of the component for more detail. - [/packages/mui-material/src/Select/Select.js](https://github.com/mui/material-ui/tree/HEAD/packages/mui-material/src/Select/Select.js)