@primer/react-brand/docs/forms/Select/index.md

Primer Brand is a GitHub's design system for creating React-based marketing websites and digital experiences.

---
title: Select
description: Use the select component to enable selection of one option from a list.
keywords: ['dropdown', 'list', 'menu', 'input', 'form']
figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=1793%3A28117'
source: https://github.com/primer/brand/blob/main/packages/react/src/forms/Select/Select.tsx
storybook: '/brand/storybook/?path=/story/components-forms-select--playground'
---

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

## Examples

### Default

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

### Placeholder

```jsx
<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

```jsx
<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/index.md)

```jsx
<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

```jsx
<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

```jsx
<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.

```jsx
<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.

```jsx
<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](https://reactjs.org/docs/uncontrolled-components.html) by forwarding a `ref` to the underlying element.

```jsx filename="noinline"
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                                   | 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select) 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option) 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/optgroup) accepted by the `<optgroup>` element.

## Related components

- [Checkbox](../Checkbox/index.md)
- [FormControl](../FormControl/index.md)
- [TextInput](../TextInput/index.md)