Select

These should never be used for short lists of items that could be better served by using radio options.

Use with caution

GDS advise against using drop-down select boxes as they have poor accessibility and can be cumbersome to use on a mobile device.

They hide the choices and can confuse users as they may not understand what they’re being asked before they see the answers by interacting with the element.

Where large lists are involved, some users may be unaware that they can scroll through the entire list to find the appropriate answer.

Because the expanded list cannot be styled, this may cause usability issues where the drop-down itself may be difficult to read for users with visual impairments.

Nunjucks

{% from "components/select/_macro.njk" import onsSelect %}
{{
    onsSelect({
        "id": "select",
        "name": "select",
        "label": {
            "text": "Question topic"
        },
        "options": [
            {
                "value": "",
                "text": "Select an option",
                "disabled": true,
                "selected": true
            },
            {
                "value": 1,
                "text": "General"
            },
            {
                "value": "people-who-live-here",
                "text": "People who live here"
            },
            {
                "value": "visitors",
                "text": "Visitors"
            },
            {
                "value": "household-accommodation",
                "text": "Household and accommodation"
            },
            {
                "value": "personal-details",
                "text": "Personal details"
            },
            {
                "value": "health",
                "text": "Health"
            },
            {
                "value": "qualifications",
                "text": "Qualifications"
            },
            {
                "value": "employment",
                "text": "Employment"
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
id	string	true	The HTML `id` of the select element. This used for the label’s `for` attribute.
classes	string	false	Classes to add to the select element
name	string	false	The HTML `name` attribute for the select element
attributes	object	false	HTML attributes (for example, data attributes) to add to the select element
label	`Object<Label>`	true	Settings for the label. The HTML `for` attribute will automatically be set to match the select id.
options	`Array<SelectOption>`	true	An array of options for the component
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes for the field
dontWrap	boolean	false	Prevents the select from being wrapped in a field component
error	`Error` (ref)	false	Configuration for validation errors

SelectOption

Name	Type	Required	Description
text	string	true	The text for the option
value	string	false	The value for the option. If not specified the value will set by the `text` parameter
selected	boolean	false	Set to “true” to make an option selected when the page loads. Only one option should have this set.
disabled	boolean	false	Set to “true” to disable an option. Use to set a default placeholder option that can’t be selected, for example, “Select an option”.
id	string	false	The HTML `id` of the option element.
attributes	object	false	HTML attributes (for example, data attributes) to add to the option element

Label

Name	Type	Required	Description
text	string	true	The text content of the label
description	string	false	Hint text to help users use the component
classes	string	false	Classes to add to the label
inline	boolean	false	Set to “true” to display the label on the same line and before the select element

HTML

<div class="ons-field">
  <label class="ons-label" for="select">Question topic</label>
  <select id="select" name="select" class="ons-input ons-input--select">
    <option value="" selected disabled>Select an option</option>
    <option value="1">General</option>
    <option value="people-who-live-here">People who live here</option>
    <option value="visitors">Visitors</option>
    <option value="household-accommodation">Household and accommodation</option>
    <option value="personal-details">Personal details</option>
    <option value="health">Health</option>
    <option value="qualifications">Qualifications</option>
    <option value="employment">Employment</option>
  </select>
</div>

Variants

Wide

Example: Example Select Wide contents

Nunjucks
Nunjucks macro options
HTML

Nunjucks

{% from "components/select/_macro.njk" import onsSelect %}
{{
    onsSelect({
        "id": "select-wide",
        "name": "select",
        "classes": "ons-input--block",
        "label": {
            "text": "Question topic"
        },
        "options": [
            {
                "value": "",
                "text": "Select an option",
                "disabled": true,
                "selected": true
            },
            {
                "value": "general",
                "text": "General"
            },
            {
                "value": "people-who-live-here",
                "text": "People who live here"
            },
            {
                "value": "visitors",
                "text": "Visitors"
            },
            {
                "value": "household-accommodation",
                "text": "Household and accommodation"
            },
            {
                "value": "personal-details",
                "text": "Personal details"
            },
            {
                "value": "health",
                "text": "Health"
            },
            {
                "value": "qualifications",
                "text": "Qualifications"
            },
            {
                "value": "employment",
                "text": "Employment"
            },
            {
                "value": "gdp",
                "text": "Gross Domestic Product figures for year ending April 2018"
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
id	string	true	The HTML `id` of the select element. This used for the label’s `for` attribute.
classes	string	false	Classes to add to the select element
name	string	false	The HTML `name` attribute for the select element
attributes	object	false	HTML attributes (for example, data attributes) to add to the select element
label	`Object<Label>`	true	Settings for the label. The HTML `for` attribute will automatically be set to match the select id.
options	`Array<SelectOption>`	true	An array of options for the component
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes for the field
dontWrap	boolean	false	Prevents the select from being wrapped in a field component
error	`Error` (ref)	false	Configuration for validation errors

SelectOption

Name	Type	Required	Description
text	string	true	The text for the option
value	string	false	The value for the option. If not specified the value will set by the `text` parameter
selected	boolean	false	Set to “true” to make an option selected when the page loads. Only one option should have this set.
disabled	boolean	false	Set to “true” to disable an option. Use to set a default placeholder option that can’t be selected, for example, “Select an option”.
id	string	false	The HTML `id` of the option element.
attributes	object	false	HTML attributes (for example, data attributes) to add to the option element

Label

Name	Type	Required	Description
text	string	true	The text content of the label
description	string	false	Hint text to help users use the component
classes	string	false	Classes to add to the label
inline	boolean	false	Set to “true” to display the label on the same line and before the select element

HTML

<div class="ons-field">
  <label class="ons-label" for="select-wide">Question topic</label>
  <select id="select-wide" name="select" class="ons-input ons-input--select ons-input--block">
    <option value="" selected disabled>Select an option</option>
    <option value="general">General</option>
    <option value="people-who-live-here">People who live here</option>
    <option value="visitors">Visitors</option>
    <option value="household-accommodation">Household and accommodation</option>
    <option value="personal-details">Personal details</option>
    <option value="health">Health</option>
    <option value="qualifications">Qualifications</option>
    <option value="employment">Employment</option>
    <option value="gdp">Gross Domestic Product figures for year ending April 2018</option>
  </select>
</div>

With inline label

Example: Example Select With Inline Label contents

Nunjucks
Nunjucks macro options
HTML

Nunjucks

{% from "components/select/_macro.njk" import onsSelect %}
{{
    onsSelect({
        "id": "select",
        "name": "select",
        "classes": "ons-u-wa--@xxs",
        "label": {
            "text": "Sort by",
            "inline": true
        },
        "options": [
            {
                "value": "best-match",
                "text": "Best match",
                "selected": true
            },
            {
                "value": "latest",
                "text": "Latest"
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
id	string	true	The HTML `id` of the select element. This used for the label’s `for` attribute.
classes	string	false	Classes to add to the select element
name	string	false	The HTML `name` attribute for the select element
attributes	object	false	HTML attributes (for example, data attributes) to add to the select element
label	`Object<Label>`	true	Settings for the label. The HTML `for` attribute will automatically be set to match the select id.
options	`Array<SelectOption>`	true	An array of options for the component
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes for the field
dontWrap	boolean	false	Prevents the select from being wrapped in a field component
error	`Error` (ref)	false	Configuration for validation errors

SelectOption

Name	Type	Required	Description
text	string	true	The text for the option
value	string	false	The value for the option. If not specified the value will set by the `text` parameter
selected	boolean	false	Set to “true” to make an option selected when the page loads. Only one option should have this set.
disabled	boolean	false	Set to “true” to disable an option. Use to set a default placeholder option that can’t be selected, for example, “Select an option”.
id	string	false	The HTML `id` of the option element.
attributes	object	false	HTML attributes (for example, data attributes) to add to the option element

Label

Name	Type	Required	Description
text	string	true	The text content of the label
description	string	false	Hint text to help users use the component
classes	string	false	Classes to add to the label
inline	boolean	false	Set to “true” to display the label on the same line and before the select element

HTML

<div class="ons-field ons-field--inline">
  <label class="ons-label" for="select">Sort by</label>
  <select id="select" name="select" class="ons-input ons-input--select ons-u-wa--@xxs">
    <option value="best-match" selected>Best match</option>
    <option value="latest">Latest</option>
  </select>
</div>

How to check drop-down selection

You should check that users have selected one of the drop-down options and show an error message if they have not.

Error messages

Use the correct errors pattern and show the error details above the drop-down.

Example: Example Select With Error contents

Nunjucks
Nunjucks macro options
HTML

Nunjucks

{% from "components/select/_macro.njk" import onsSelect %}

{{
    onsSelect({
        "id": "select",
        "name": "select",
        "label": {
            "text": "Question topic"
        },
        "label": {
            "text": "Question topic"
        },
        "options": [
            {
                "value": "",
                "text": "Select an option",
                "disabled": true,
                "selected": true
            },
            {
                "value": "general",
                "text": "General"
            },
            {
                "value": "people-who-live-here",
                "text": "People who live here"
            },
            {
                "value": "visitors",
                "text": "Visitors"
            },
            {
                "value": "household-accommodation",
                "text": "Household and accommodation"
            },
            {
                "value": "personal-details",
                "text": "Personal details"
            },
            {
                "value": "health",
                "text": "Health"
            },
            {
                "value": "qualifications",
                "text": "Qualifications"
            },
            {
                "value": "employment",
                "text": "Employment"
            }
        ],
        "error": {
            "id": "select-error",
            "text": "Select a question topic"
        }
    })
}}

Nunjucks macro options

Name	Type	Required	Description
id	string	true	The HTML `id` of the select element. This used for the label’s `for` attribute.
classes	string	false	Classes to add to the select element
name	string	false	The HTML `name` attribute for the select element
attributes	object	false	HTML attributes (for example, data attributes) to add to the select element
label	`Object<Label>`	true	Settings for the label. The HTML `for` attribute will automatically be set to match the select id.
options	`Array<SelectOption>`	true	An array of options for the component
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes for the field
dontWrap	boolean	false	Prevents the select from being wrapped in a field component
error	`Error` (ref)	false	Configuration for validation errors

SelectOption

Name	Type	Required	Description
text	string	true	The text for the option
value	string	false	The value for the option. If not specified the value will set by the `text` parameter
selected	boolean	false	Set to “true” to make an option selected when the page loads. Only one option should have this set.
disabled	boolean	false	Set to “true” to disable an option. Use to set a default placeholder option that can’t be selected, for example, “Select an option”.
id	string	false	The HTML `id` of the option element.
attributes	object	false	HTML attributes (for example, data attributes) to add to the option element

Label

Name	Type	Required	Description
text	string	true	The text content of the label
description	string	false	Hint text to help users use the component
classes	string	false	Classes to add to the label
inline	boolean	false	Set to “true” to display the label on the same line and before the select element

HTML

<div class="ons-panel ons-panel--error ons-panel--no-title" id="select-error">
  <span class="ons-panel__assistive-text ons-u-vh">Error: </span>
  <div class="ons-panel__body">
    <p class="ons-panel__error">
      <strong>Select a question topic</strong>
    </p>
    <div class="ons-field">
      <label class="ons-label" for="select">Question topic</label>
      <select id="select" name="select" class="ons-input ons-input--select ons-input--error">
        <option value="" selected disabled>Select an option</option>
        <option value="general">General</option>
        <option value="people-who-live-here">People who live here</option>
        <option value="visitors">Visitors</option>
        <option value="household-accommodation">Household and accommodation</option>
        <option value="personal-details">Personal details</option>
        <option value="health">Health</option>
        <option value="qualifications">Qualifications</option>
        <option value="employment">Employment</option>
      </select>
    </div>
  </div>
</div>

If a drop-down option has not been selected

Use “Select [whatever topic the drop-down is asking for]”.
For example, “Select a question topic”.

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss the ‘Select’ component on GitHub (opens in a new tab)

Cookies on ons.gov.uk

BETA

Select

Example: Example Select contents

Nunjucks

Nunjucks macro options

SelectOption

Label

HTML

Variants

Wide

Example: Example Select Wide contents

Nunjucks

Nunjucks macro options

SelectOption

Label

HTML

With inline label

Example: Example Select With Inline Label contents

Nunjucks

Nunjucks macro options

SelectOption

Label

HTML

How to check drop-down selection

Error messages

Example: Example Select With Error contents

Nunjucks

Nunjucks macro options

SelectOption

Label

HTML

If a drop-down option has not been selected

Help improve this page