Label
Overview
Labels describe the purpose of an:
! Warning:
All input and textarea components must have a visible label
Example Label contents
Nunjucks
{% from "components/label/_macro.njk" import onsLabel %}
{{
onsLabel({
"id": 'label',
"for": "some-input",
"text": 'Label'
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id for the label |
| text | string | true | The text content of the label |
| for | string | true | The id of the input the label is for |
| description | string | false | Hint text following the label to help users answer |
| classes | string | false | Classes to add to the label |
| attributes | object | false | HTML attributes to add to the label, for example, data attributes |
| inputType | string | false | Set to “radio” or “checkbox” to add the relevant CSS for checkboxes or radios. Defaults to text input. |
| accessiblePlaceholder | boolean | false | Will add the provided label as an accessible placeholder within the input |
HTML
<label class="ons-label" for="some-input" id="label">Label</label>How to use this component
Usually, you will not need to implement a label yourself as the form inputs have them imported in their respective templates.
You should make sure the label is:
- short, direct and written in sentence case
- left-aligned
You should not:
- use placeholder text to display a label as it will not be visible when the user clicks on the input
- place a colon at the end of the label
Variants
With description
Use this to show a hint that tells most users either:
- how to enter their information
- how to find the information they need to enter
- how their information will be used
To do this, use the optional description parameter.
Example Label With Description contents
Nunjucks
{% from "components/label/_macro.njk" import onsLabel %}
{{
onsLabel({
"text": "Label",
"for": "some-input",
"description": "An example description"
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id for the label |
| text | string | true | The text content of the label |
| for | string | true | The id of the input the label is for |
| description | string | false | Hint text following the label to help users answer |
| classes | string | false | Classes to add to the label |
| attributes | object | false | HTML attributes to add to the label, for example, data attributes |
| inputType | string | false | Set to “radio” or “checkbox” to add the relevant CSS for checkboxes or radios. Defaults to text input. |
| accessiblePlaceholder | boolean | false | Will add the provided label as an accessible placeholder within the input |
HTML
<label class="ons-label ons-label--with-description" for="some-input" aria-describedby="description-hint">Label</label>
<span id="description-hint" class="ons-label__description ons-input--with-description">An example description</span>Inline
To place a label in front of the input, set the optional inline parameter to “true”.
This should only be used when an input needs to be displayed alongside another element, for example, a sort filter.
Example Select With Inline Label contents
Nunjucks
{% from "components/select/_macro.njk" import onsSelect %}
{{
onsSelect({
"id": "select-example-with-inline-label",
"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 |
| 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 |
| 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-example-with-inline-label">Sort by</label>
<select id="select-example-with-inline-label" 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>Checkbox and radio labels
To label radios and checkboxes, inputType needs to be set to radio or checkbox.
Example Radios With Descriptions contents
Nunjucks
{% from "components/radios/_macro.njk" import onsRadios %}
{% from "components/question/_macro.njk" import onsQuestion %}
{% call onsQuestion({
"title": "What is your ethnic group or background?",
"classes": "ons-u-mt-no",
"legendIsQuestionTitle": true
}) %}
{{
onsRadios({
"dontWrap": true,
"name": "ethnicity",
"radios": [
{
"id": "white-example-radio-with-description",
"label": {
"text": "White",
"description": "Includes British, Northern Irish, Irish, Gypsy, Irish Traveller, Roma or any other White background"
},
"name": "white"
},
{
"id": "mixed-example-radio-with-description",
"label": {
"text": "Mixed or Multiple ethnic groups",
"description": "Includes White and Black Caribbean, White and Black African, White and Asian or any other Mixed or Multiple background"
},
"name": "mixed"
},
{
"id": "asian-example-radio-with-description",
"label": {
"text": "Asian or Asian British",
"description": "Includes Indian, Pakistani, Bangladeshi, Chinese or any other Asian background"
},
"name": "asian"
},
{
"id": "black-example-radio-with-description",
"label": {
"text": "Black, Black British, Caribbean or African",
"description": "Includes Black British, Caribbean, African or any other Black background"
},
"name": "black"
},
{
"id": "other-example-radio-with-description",
"label": {
"text": "Other ethnic group",
"description": "Includes Arab or any other ethnic group"
},
"name": "other"
}
]
})
}}
{% endcall %}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id for the fieldset |
| classes | string | false | Classes to add to the fieldset |
| legend | string | true (unless dontWrap is set) | The HTML <legend> for the fieldset |
| legendClasses | string | false | Classes to add to the legend |
| description | string | false | Hint text following the fieldset‘s legend to help users answer |
| borderless | boolean | false | Set to “true” to remove the border surrounding the input and label |
| name | string | true | The name to apply to the radios |
| radios | array<Radio> | true | Settings for each radio |
| dontWrap | boolean | false | Set to “true” to prevent the radios from being wrapped in a fieldset component |
| legendIsQuestionTitle | boolean | false | Creates an h1 inside the legend. Use when the radios are the only fieldset on the page |
| value | string | false | Set to “true” to preset the checked radio. This can also be achieved by setting the checked parameter on the Radio item to “true”. |
| error | Error (ref) | false | Configuration for validation errors |
| or | string | false | Text for the “Or” seperator label |
| clearRadios | object<ClearRadios> | false | Settings for for the clear selection button |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the radio. Used for the label’s for attribute. |
| value | string | false | The HTML value attribute for the radio to set a preset value for the input |
| classes | string | false | Classes to add to the radio |
| checked | boolean | false | Set to “true” to select the radio when the page loads |
| label | Label (ref) | true | Settings for the radio label |
| other | object<OtherRadio> with arrays if using Select (ref), Checkboxes (ref) or Radios (ref) | false | Settings for a nested input, select, checkboxes, radios or textarea to provide other information in addition to the radio answer. Defaults to use input. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the radio input element |
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The HTML id of the nested input. Used for the label’s for attribute. |
| classes | string | false | Classes to add to the nested input |
| name | string | false | The HTML name attribute for the nested input |
| value | string | false | The HTML value attribute for the nested input to set a preset value for the input |
| label | Label (ref) | true | Settings for the nested input’s label |
| width | string | false | Required width of the nested text input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”. Defaults to “auto”. |
| type | string | false | Sets the HTML type attribute for the nested <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”. |
| inputClasses | string | false | Classes to apply to the radio input element |
| otherType | string | false (unless alternative input used) | Set the type of nested input if not using default text input, using available types: “select”, “checkboxes”, “radios” or “textarea”. |
| open | boolean | false | Set to “true” to show the nested other input when page loads |
| selectAllChildren | boolean | false | Set to “true” when using otherType set to “checkboxes” to show all nested checkboxes pre-selected |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the nested input |
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true | The text label for the button |
| name | string | false | The HTML name attribute for the button |
| ariaClearText | string | true | The text to be announced to screen readers when a radio has been selected. For example, “You can clear your answer using the “clear selection” button after the radio inputs”. |
| ariaClearedText | string | true | The text to be announced to screen readers when the “clear selection” button has been selected. For example, “Your answer has been cleared”. |
HTML
<div class="ons-question ons-u-mb-l ons-u-mt-no">
<div class="ons-question__answer ons-u-mb-m">
<fieldset class="ons-fieldset">
<legend class="ons-fieldset__legend ons-u-mb-no">
<h1 id="fieldset-legend-title" class="ons-fieldset__legend-title">What is your ethnic group or background?</h1>
</legend>
<div class="ons-input-items">
<div class="ons-radios__items">
<span class="ons-radios__item">
<span class="ons-radio">
<input type="radio" id="white-example-radio-with-description" class="ons-radio__input ons-js-radio"
value="" name="ethnicity">
<label class=" ons-radio__label ons-label--with-description" for="white-example-radio-with-description"
aria-describedby="white-example-radio-with-description-label-description-hint"
id="white-example-radio-with-description-label">White<span class="ons-label__aria-hidden-description"
aria-hidden="true">
<span class="ons-label__description ons-radio__label--with-description">Includes British, Northern
Irish, Irish, Gypsy, Irish Traveller, Roma or any other White background</span></span></label>
<span class="ons-label__visually-hidden-description ons-u-vh"
id="white-example-radio-with-description-label-description-hint">Includes British, Northern Irish,
Irish, Gypsy, Irish Traveller, Roma or any other White background</span>
</span>
</span>
<br>
<span class="ons-radios__item">
<span class="ons-radio">
<input type="radio" id="mixed-example-radio-with-description" class="ons-radio__input ons-js-radio"
value="" name="ethnicity">
<label class=" ons-radio__label ons-label--with-description" for="mixed-example-radio-with-description"
aria-describedby="mixed-example-radio-with-description-label-description-hint"
id="mixed-example-radio-with-description-label">Mixed or Multiple ethnic groups<span
class="ons-label__aria-hidden-description" aria-hidden="true">
<span class="ons-label__description ons-radio__label--with-description">Includes White and Black
Caribbean, White and Black African, White and Asian or any other Mixed or Multiple
background</span></span></label>
<span class="ons-label__visually-hidden-description ons-u-vh"
id="mixed-example-radio-with-description-label-description-hint">Includes White and Black Caribbean,
White and Black African, White and Asian or any other Mixed or Multiple background</span>
</span>
</span>
<br>
<span class="ons-radios__item">
<span class="ons-radio">
<input type="radio" id="asian-example-radio-with-description" class="ons-radio__input ons-js-radio"
value="" name="ethnicity">
<label class=" ons-radio__label ons-label--with-description" for="asian-example-radio-with-description"
aria-describedby="asian-example-radio-with-description-label-description-hint"
id="asian-example-radio-with-description-label">Asian or Asian British<span
class="ons-label__aria-hidden-description" aria-hidden="true">
<span class="ons-label__description ons-radio__label--with-description">Includes Indian, Pakistani,
Bangladeshi, Chinese or any other Asian background</span></span></label>
<span class="ons-label__visually-hidden-description ons-u-vh"
id="asian-example-radio-with-description-label-description-hint">Includes Indian, Pakistani,
Bangladeshi, Chinese or any other Asian background</span>
</span>
</span>
<br>
<span class="ons-radios__item">
<span class="ons-radio">
<input type="radio" id="black-example-radio-with-description" class="ons-radio__input ons-js-radio"
value="" name="ethnicity">
<label class=" ons-radio__label ons-label--with-description" for="black-example-radio-with-description"
aria-describedby="black-example-radio-with-description-label-description-hint"
id="black-example-radio-with-description-label">Black, Black British, Caribbean or African<span
class="ons-label__aria-hidden-description" aria-hidden="true">
<span class="ons-label__description ons-radio__label--with-description">Includes Black British,
Caribbean, African or any other Black background</span></span></label>
<span class="ons-label__visually-hidden-description ons-u-vh"
id="black-example-radio-with-description-label-description-hint">Includes Black British, Caribbean,
African or any other Black background</span>
</span>
</span>
<br>
<span class="ons-radios__item">
<span class="ons-radio">
<input type="radio" id="other-example-radio-with-description" class="ons-radio__input ons-js-radio"
value="" name="ethnicity">
<label class=" ons-radio__label ons-label--with-description" for="other-example-radio-with-description"
aria-describedby="other-example-radio-with-description-label-description-hint"
id="other-example-radio-with-description-label">Other ethnic group<span
class="ons-label__aria-hidden-description" aria-hidden="true">
<span class="ons-label__description ons-radio__label--with-description">Includes Arab or any other
ethnic group</span></span></label>
<span class="ons-label__visually-hidden-description ons-u-vh"
id="other-example-radio-with-description-label-description-hint">Includes Arab or any other ethnic
group</span>
</span>
</span>
</div>
</div>
</fieldset>
</div>
</div>Help improve this page
Let us know how we could improve this page, or share your user research findings. Discuss the ‘Label’ component on GitHub (opens in a new tab)