Select - Primer


import {Select} from '@primer/react-brand'

Examples

Default

<Select aria-label="Select a handle">
  <Select.Option value="mona">Monalisa</Select.Option>
  <Select.Option value="hubot">Hubot</Select.Option>
</Select>

Placeholder

<Select defaultValue="" aria-label="Select a handle">
  <Select.Option value="" disabled>
    Select a handle
  </Select.Option>
  <Select.Option value="mona">Monalisa</Select.Option>
  <Select.Option value="hubot">Hubot</Select.Option>
</Select>

Option groups

<Select defaultValue="" aria-label="Select a country">
  <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 with `FormControl`

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>

Validation

<div style={{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>
</div>

Full width

<Select fullWidth aria-label="Select a handle">
  <Select.Option value="mona">Monalisa</Select.Option>
  <Select.Option value="hubot">Hubot</Select.Option>
</Select>

Sizes

FormControl can appear in medium and large dimensions using the size prop.

<div style={{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>
</div>

Required

Pass the required prop to ensure that the input field must be filled out before submitting the form.

<Select required defaultValue="" aria-label="Select a handle">
  <Select.Option value="" disabled>
    Select a handle
  </Select.Option>
  <Select.Option value="mona">Monalisa</Select.Option>
  <Select.Option value="hubot">Hubot</Select.Option>
</Select>

Using `refs`

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}>
      <div
        style={{
          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>
      </div>
    </form>
  )
}
 
render(App)

Component props

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.

Select Required

Name	Type	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.

Select.Option Required

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.

Select.OptGroup

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.