Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

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.

Example: Example Select contents

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

NameTypeRequiredDescription
idstringtrueThe HTML id of the select element. This used for the label’s for attribute.
classesstringfalseClasses to add to the select element
namestringfalseThe HTML name attribute for the select element
attributesobjectfalseHTML attributes (for example, data attributes) to add to the select element
labelObject<Label>trueSettings for the label. The HTML for attribute will automatically be set to match the select id.
optionsArray<SelectOption>trueAn array of options for the component
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses for the field
dontWrapbooleanfalsePrevents the select from being wrapped in a field component
errorError (ref)falseConfiguration for validation errors

SelectOption

NameTypeRequiredDescription
textstringtrueThe text for the option
valuestringfalseThe value for the option. If not specified the value will set by the text parameter
selectedbooleanfalseSet to “true” to make an option selected when the page loads. Only one option should have this set.
disabledbooleanfalseSet to “true” to disable an option. Use to set a default placeholder option that can’t be selected, for example, “Select an option”.
idstringfalseThe HTML id of the option element.
attributesobjectfalseHTML attributes (for example, data attributes) to add to the option element

Label

NameTypeRequiredDescription
textstringtrueThe text content of the label
descriptionstringfalseHint text to help users use the component
classesstringfalseClasses to add to the label
inlinebooleanfalseSet 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

{% 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

NameTypeRequiredDescription
idstringtrueThe HTML id of the select element. This used for the label’s for attribute.
classesstringfalseClasses to add to the select element
namestringfalseThe HTML name attribute for the select element
attributesobjectfalseHTML attributes (for example, data attributes) to add to the select element
labelObject<Label>trueSettings for the label. The HTML for attribute will automatically be set to match the select id.
optionsArray<SelectOption>trueAn array of options for the component
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses for the field
dontWrapbooleanfalsePrevents the select from being wrapped in a field component
errorError (ref)falseConfiguration for validation errors

SelectOption

NameTypeRequiredDescription
textstringtrueThe text for the option
valuestringfalseThe value for the option. If not specified the value will set by the text parameter
selectedbooleanfalseSet to “true” to make an option selected when the page loads. Only one option should have this set.
disabledbooleanfalseSet to “true” to disable an option. Use to set a default placeholder option that can’t be selected, for example, “Select an option”.
idstringfalseThe HTML id of the option element.
attributesobjectfalseHTML attributes (for example, data attributes) to add to the option element

Label

NameTypeRequiredDescription
textstringtrueThe text content of the label
descriptionstringfalseHint text to help users use the component
classesstringfalseClasses to add to the label
inlinebooleanfalseSet 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

{% 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

NameTypeRequiredDescription
idstringtrueThe HTML id of the select element. This used for the label’s for attribute.
classesstringfalseClasses to add to the select element
namestringfalseThe HTML name attribute for the select element
attributesobjectfalseHTML attributes (for example, data attributes) to add to the select element
labelObject<Label>trueSettings for the label. The HTML for attribute will automatically be set to match the select id.
optionsArray<SelectOption>trueAn array of options for the component
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses for the field
dontWrapbooleanfalsePrevents the select from being wrapped in a field component
errorError (ref)falseConfiguration for validation errors

SelectOption

NameTypeRequiredDescription
textstringtrueThe text for the option
valuestringfalseThe value for the option. If not specified the value will set by the text parameter
selectedbooleanfalseSet to “true” to make an option selected when the page loads. Only one option should have this set.
disabledbooleanfalseSet to “true” to disable an option. Use to set a default placeholder option that can’t be selected, for example, “Select an option”.
idstringfalseThe HTML id of the option element.
attributesobjectfalseHTML attributes (for example, data attributes) to add to the option element

Label

NameTypeRequiredDescription
textstringtrueThe text content of the label
descriptionstringfalseHint text to help users use the component
classesstringfalseClasses to add to the label
inlinebooleanfalseSet 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

{% 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

NameTypeRequiredDescription
idstringtrueThe HTML id of the select element. This used for the label’s for attribute.
classesstringfalseClasses to add to the select element
namestringfalseThe HTML name attribute for the select element
attributesobjectfalseHTML attributes (for example, data attributes) to add to the select element
labelObject<Label>trueSettings for the label. The HTML for attribute will automatically be set to match the select id.
optionsArray<SelectOption>trueAn array of options for the component
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses for the field
dontWrapbooleanfalsePrevents the select from being wrapped in a field component
errorError (ref)falseConfiguration for validation errors

SelectOption

NameTypeRequiredDescription
textstringtrueThe text for the option
valuestringfalseThe value for the option. If not specified the value will set by the text parameter
selectedbooleanfalseSet to “true” to make an option selected when the page loads. Only one option should have this set.
disabledbooleanfalseSet to “true” to disable an option. Use to set a default placeholder option that can’t be selected, for example, “Select an option”.
idstringfalseThe HTML id of the option element.
attributesobjectfalseHTML attributes (for example, data attributes) to add to the option element

Label

NameTypeRequiredDescription
textstringtrueThe text content of the label
descriptionstringfalseHint text to help users use the component
classesstringfalseClasses to add to the label
inlinebooleanfalseSet 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)