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