Design System

Select Input

Form select inputs are used when the user has a choice of many options eg choosing a country or a county

Intended behaviour

If you use the component for settings, you can make an option pre-selected by default when users first see it.

If you use the component for questions, you should not pre-select any of the options in case it influences users’ answers.

When to use this component

The select component allows users to choose an option from a long list. The select component should only be used as a last resort in public-facing services because research shows that some users find selects very difficult to use.

When not to use this component

The select component allows users to choose an option from a long list. Before using the select component, try asking users questions which will allow you to present them with fewer options.

Variations

Minimal input

open this example in its own window 

<label for="ds-id-0" class="form-label">Colour</label>
<select class="form-select" aria-label="Colour">
  <option value="red">Red</option>
  <option value="green">Green</option>
  <option value="blue">Blue</option>
</select>

Options to the selectInput() macro

label: string

The human-readable input label.

options: object

Keys are each option's value, and values are options' human-readable value labels.

value: stringnull

The value of the currently selected option.

required: boolean = false

Whether the input is required.

disabled: boolean = false

Whether the input must be disabled.

invalid: boolean = false

Whether the input's state is valid.

id: string|null = null

The element's ID.

{% from 'macros/component/select-input.html' import selectInput %}

{{ selectInput({
    'label': 'Colour',
    'options': {
        'red': 'Red',
        'green': 'Green',
        'blue': 'Blue'
    }
}) }}

Required input

open this example in its own window 

<label for="ds-id-1" class="form-label">Colour</label>
<select class="form-select" aria-label="Colour" required>
  <option value="red">Red</option>
  <option value="green">Green</option>
  <option value="blue">Blue</option>
</select>

Options to the selectInput() macro

label: string

The human-readable input label.

options: object

Keys are each option's value, and values are options' human-readable value labels.

value: stringnull

The value of the currently selected option.

required: boolean = false

Whether the input is required.

disabled: boolean = false

Whether the input must be disabled.

invalid: boolean = false

Whether the input's state is valid.

id: string|null = null

The element's ID.

{% from 'macros/component/select-input.html' import selectInput %}

{{ selectInput({
    'label': 'Colour',
    'options': {
        'red': 'Red',
        'green': 'Green',
        'blue': 'Blue'
    },
    'required': true
}) }}

Invalid input

open this example in its own window 

<label for="ds-id-2" class="form-label">Colour</label>
<select class="form-select is-invalid" aria-label="Colour">
  <option value="red">Red</option>
  <option value="green">Green</option>
  <option value="blue">Blue</option>
</select>

Options to the selectInput() macro

label: string

The human-readable input label.

options: object

Keys are each option's value, and values are options' human-readable value labels.

value: stringnull

The value of the currently selected option.

required: boolean = false

Whether the input is required.

disabled: boolean = false

Whether the input must be disabled.

invalid: boolean = false

Whether the input's state is valid.

id: string|null = null

The element's ID.

{% from 'macros/component/select-input.html' import selectInput %}

{{ selectInput({
    'label': 'Colour',
    'options': {
        'red': 'Red',
        'green': 'Green',
        'blue': 'Blue'
    },
    'invalid': true
}) }}

Disabled input

open this example in its own window 

<label for="ds-id-3" class="form-label">Colour</label>
<select class="form-select" aria-label="Colour" disabled>
  <option value="red">Red</option>
  <option value="green">Green</option>
  <option value="blue">Blue</option>
</select>

Options to the selectInput() macro

label: string

The human-readable input label.

options: object

Keys are each option's value, and values are options' human-readable value labels.

value: stringnull

The value of the currently selected option.

required: boolean = false

Whether the input is required.

disabled: boolean = false

Whether the input must be disabled.

invalid: boolean = false

Whether the input's state is valid.

id: string|null = null

The element's ID.

{% from 'macros/component/select-input.html' import selectInput %}

{{ selectInput({
    'label': 'Colour',
    'options': {
        'red': 'Red',
        'green': 'Green',
        'blue': 'Blue'
    },
    'disabled': true
}) }}

Prepopulated input

open this example in its own window 

<label for="ds-id-4" class="form-label">Colour</label>
<select class="form-select" aria-label="Colour">
  <option value="red">Red</option>
  <option value="green">Green</option>
  <option value="blue" selected>Blue</option>
</select>

Options to the selectInput() macro

label: string

The human-readable input label.

options: object

Keys are each option's value, and values are options' human-readable value labels.

value: stringnull

The value of the currently selected option.

required: boolean = false

Whether the input is required.

disabled: boolean = false

Whether the input must be disabled.

invalid: boolean = false

Whether the input's state is valid.

id: string|null = null

The element's ID.

{% from 'macros/component/select-input.html' import selectInput %}

{{ selectInput({
    'label': 'Colour',
    'options': {
        'red': 'Red',
        'green': 'Green',
        'blue': 'Blue'
    },
    'value': 'blue'
}) }}