Select
Use the select component to enable selection of one option from a list.
- Experimental
- Not reviewed for accessibility
import {Select} from '@primer/react-brand'
<Select>
<Select.Option value="mona">Monalisa</Select.Option>
<Select.Option value="hubot">Hubot</Select.Option>
</Select>
<Select defaultValue="">
<Select.Option value="" disabled>
Select a handle
</Select.Option>
<Select.Option value="mona">Monalisa</Select.Option>
<Select.Option value="hubot">Hubot</Select.Option>
</Select>
<Select defaultValue="">
<Select.Option value="" disabled>
Select a country
</Select.Option>
<Select.OptGroup label="Asia">
<Select.Option value="cn">China</Select.Option>
</Select.OptGroup>
<Select.OptGroup label="Europe">
<Select.Option value="fr">France</Select.Option>
<Select.Option value="it">Italy</Select.Option>
<Select.Option value="es">Spain</Select.Option>
<Select.Option value="uk">United Kingdom</Select.Option>
</Select.OptGroup>
<Select.OptGroup label="Americas">
<Select.Option value="mx">Mexico</Select.Option>
<Select.Option value="us">United States</Select.Option>
</Select.OptGroup>
</Select>
Use Select alongside FormControl to ensure the control has a corresponding form label.
See FormControl for additional usage examples.
<FormControl>
<FormControl.Label>Country</FormControl.Label>
<Select defaultValue="">
<Select.Option value="" disabled>
Select a country
</Select.Option>
<Select.Option value="cn">China</Select.Option>
<Select.Option value="fr">France</Select.Option>
<Select.Option value="it">Italy</Select.Option>
<Select.Option value="mx">Mexico</Select.Option>
<Select.Option value="es">Spain</Select.Option>
<Select.Option value="uk">United Kingdom</Select.Option>
<Select.Option value="us">United States</Select.Option>
</Select>
</FormControl>
<Container sx={{display: 'inline-grid', gap: 3}}>
<FormControl validationStatus="error">
<FormControl.Label>Error</FormControl.Label>
<Select>
<Select.Option value="mona">Monalisa</Select.Option>
<Select.Option value="hubot">Hubot</Select.Option>
</Select>
<FormControl.Validation>This is an error message</FormControl.Validation>
</FormControl>
<FormControl validationStatus="success">
<FormControl.Label>Success</FormControl.Label>
<Select>
<Select.Option value="mona">Monalisa</Select.Option>
<Select.Option value="hubot">Hubot</Select.Option>
</Select>
<FormControl.Validation>This is a success message</FormControl.Validation>
</FormControl>
</Container>
<Select fullWidth>
<Select.Option value="mona">Monalisa</Select.Option>
<Select.Option value="hubot">Hubot</Select.Option>
</Select>
FormControl can appear in medium and large dimensions using the size prop.
<Container sx={{display: 'inline-grid', gap: 3}}>
<FormControl size="medium">
<FormControl.Label>Medium</FormControl.Label>
<Select>
<Select.Option value="mona">Monalisa</Select.Option>
<Select.Option value="hubot">Hubot</Select.Option>
</Select>
</FormControl>
<FormControl size="large">
<FormControl.Label>Large</FormControl.Label>
<Select>
<Select.Option value="mona">Monalisa</Select.Option>
<Select.Option value="hubot">Hubot</Select.Option>
</Select>
</FormControl>
</Container>
Pass the required prop to ensure that the input field must be filled out before submitting the form.
<Select required defaultValue="">
<Select.Option value="" disabled>
Select a handle
</Select.Option>
<Select.Option value="mona">Monalisa</Select.Option>
<Select.Option value="hubot">Hubot</Select.Option>
</Select>
Select inputs can be used in uncontrolled mode by forwarding a ref to the underlying element.
const App = () => {
const selectRef = React.useRef(null)
const handleSubmit = (e) => {
e.preventDefault()
if (!selectRef.current.value) {
alert(`Select a handle to continue`)
return
}
alert(`Name: ${selectRef.current.value}`)
}
return (
<form onSubmit={handleSubmit}>
<Container
sx={{
display: 'grid',
gap: 'var(--base-size-16)',
maxWidth: 400,
marginX: 'auto',
}}
>
<FormControl fullWidth>
<FormControl.Label>Name</FormControl.Label>
<Select ref={selectRef} defaultValue="">
<Select.Option value="" disabled>
Select a handle
</Select.Option>
<Select.Option value="mona">Monalisa</Select.Option>
<Select.Option value="hubot">Hubot</Select.Option>
</Select>
</FormControl>
<Button type="submit" variant="primary">
Submit
</Button>
</Container>
</form>
)
}
render(App)
Select provides a React-based alternative to the native HTML <select>, <option> and <optgroup> elements.
The component API supports all standard HTML attribute props, while providing some additional behaviour as described below.
| Name | Type | Default | Description |
|---|
children | 'Select.Option'
'Select.OptGroup'
, | | Valid child nodes |
className | string | | Sets a custom class |
id | string | | Sets a custom id |
fullWidth | boolean | | Stretches elements visually to the edges of its parent container. |
ref | React.RefObject | | Forward a Ref to the underlying DOM node |
size | 'medium'
'large'
| | Visual dimensions for the input |
validationStatus | 'error'
'success'
| | Applies visual and semantic state to the underlying elements |
Additional props can be passed to the <select> element. See MDN for a list of props accepted by the <select> element.
| Name | Type | Default | Description |
|---|
value | string | | The value to be supplied during form subsmission. |
Additional props can be passed to the <option> element. See MDN for a list of props accepted by the <option> element.
| Name | Type | Default | Description |
|---|
label | string | | The name of the group of options. |
Additional props can be passed to the <optgroup> element. See MDN for a list of props accepted by the <optgroup> element.