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

Input

Overview

The input component lets users enter answers using alphanumeric characters that are no longer than one line, using the appropriate keyboard on touch devices.

Example Input Text contents

Nunjucks

{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "text-example-input",
        "label": {
            "text": "Enter some text"
        }
    })
}}

Nunjucks macro options

NameTypeRequiredDescription
idstringtrueThe HTML id of the input. Used for the label’s for attribute.
typestringfalseSets the HTML type attribute for the <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classesstringfalseClasses to add to the input
widthstringfalseRequired width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
namestringfalseThe HTML name attribute for the input
valuestring or integerfalseThe HTML value for the input to set a preset value for the field
minintegerfalseThe HTML min attribute to set the minimum accepted number or date for the input
maxintegerfalseThe HTML max attribute to set the maximum accepted number or date for the input
minLengthintegerfalseThe HTML minlength attribute to set the minimum accepted length of input value
maxLengthintegerfalseThe HTML maxlength attribute to set the maximum accepted length of input value
attributesobjectfalseHTML attributes (for example, data attributes) to add to the input
labelLabel (ref)falseSettings for the input label. for will automatically be set to match the input id
prefixobject <InputPrefix>falseSettings for the input prefix
suffixobject <InputSuffix>falseSettings for the input suffix
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalsePrevents the input from being wrapped in a field
mutuallyExclusiveMutuallyExclusive (ref)falseConfiguration object to set if the input has a mutually exclusive opposing option
charCheckLimitobject <CharCheckLimit>falseSettings for a character counter or limit checker on the input
legendstringfalse (unless mutuallyExclusive is set)Text for the mutually exclusive fieldset‘s legend
legendClassesstringfalseClasses to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitlebooleantrue (unless legend is set)Creates an h1 inside the legend. Use when there is only a single fieldset on the page.
errorError (ref)falseConfiguration for validation errors
autocompletestringfalseThe HTML autocomplete attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholderbooleanfalseWill use the label provided as an accessible placeholder within the input
searchButtonobject <SearchButton>falseSettings for the search input button
postTextboxLinkTextstringfalseThe text for a link following the input
postTextboxLinkUrlstringfalseThe URL for the HTML href attribute of the link following the textbox
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
InputPrefix/InputSuffix
NameTypeRequiredDescription
textstringtrueThe visible text abbreviation for the prefix or suffix, for example, “cm“
titlestringfalseThe HTML title attribute for the <abbr> element, required if the visible text label is an abbreviation. Use to write out the long form of an abbreviated prefix or suffix. For example, if text is “€”, title should be “Euro (EUR)”.
idstringtrueThe HTML id of the <abbr> element used for the prefix or suffix. Used for the input’s aria-labelledby attribute.
CharCheckLimit
NameTypeRequiredDescription
idstringtrueThe HTML id of the component
limitintegertrueThe maximum number of characters allowed in the input
charCountOverLimitPluralstringtrueThe string displayed when user has entered more than one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} characters too many”.
charCountOverLimitSingularstringtrueThe string displayed when user has entered one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} character too many”.
charcheckCountdownbooleanfalseSet to “true” to show the character limit counter as characters are entered into the input
charCountPluralstringtrueThe string displayed when multiple characters can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} characters remaining”.
charCountSingularstringtrueThe string displayed when only one more character can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} character remaining”.
SearchButton
NameTypeRequiredDescription
textstringtrueText for the button label
typestringfalseSets the HTML type attribute for the <button>. Can be set to either: “submit” or “reset”. Defaults to “button”.
idstringfalseSets the HTML id attribute for the button
classesstringfalseClasses to add to the button component
iconTypestringfalseAdds an icon to the button, before the label, by setting the icon type
attributesobjectfalseHTML attributes (for example, data attributes) to add to the button component

HTML

<div class="ons-field">
  <label class="ons-label" for="text-example-input">Enter some text</label>
  <input type="text" id="text-example-input" class="ons-input ons-input--text ons-input-type__input" />
</div>

When to use this component

Use this component when you need to let users enter information, such as their telephone number or email address.

There is specific guidance on how to input:

When not to use this component

If you need to let users enter information that will span more than one line, use the textarea component.

How to use this component

All input components must have a visible label.

You can also display hint text using a label with a description (opens in a new tab) .

Size inputs based on the type of content that you want a user to enter.

By default, the input component will fill the width of its container when the width of the viewport is below the small breakpoint. After that width it is limited to 20rem.

To make the input smaller, use a width constraint class.

Autocomplete

Use this to help the user fill out a form faster by allowing their browser to autofill the information for them.

To allow a browser to autofill an input, specify its purpose by using the autocomplete attribute.

You will need to use the autocomplete attribute for each applicable input to meet WCAG 2.1 accessibility AA requirements on input purpose (opens in a new tab) 

Width constrained

The width of inputs should be set to suit the type of content that users need to enter.

To calculate the width to constrain to, you need to set a type and a width value.

The type will determine if the input will contain text or numbers. Text will be used by default.

The width value defines how wide the input is based on the widest letter (W) or the widest number (4). For example, if you set type: text and width: 3, this will constrain the input to the width of ‘WWW’.

The width values available for both types range from “1” to “10” and “15”, “20”, “30”, “40” and “50”.

Example Input Number contents

Nunjucks
{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "number-example-input",
        "type": "number",
        "width": "2",
        "autocomplete": "off",
        "attributes": {
            "min": 0
        },
        "label": {
            "text": "Number of bedrooms"
        }
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueThe HTML id of the input. Used for the label’s for attribute.
typestringfalseSets the HTML type attribute for the <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classesstringfalseClasses to add to the input
widthstringfalseRequired width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
namestringfalseThe HTML name attribute for the input
valuestring or integerfalseThe HTML value for the input to set a preset value for the field
minintegerfalseThe HTML min attribute to set the minimum accepted number or date for the input
maxintegerfalseThe HTML max attribute to set the maximum accepted number or date for the input
minLengthintegerfalseThe HTML minlength attribute to set the minimum accepted length of input value
maxLengthintegerfalseThe HTML maxlength attribute to set the maximum accepted length of input value
attributesobjectfalseHTML attributes (for example, data attributes) to add to the input
labelLabel (ref)falseSettings for the input label. for will automatically be set to match the input id
prefixobject <InputPrefix>falseSettings for the input prefix
suffixobject <InputSuffix>falseSettings for the input suffix
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalsePrevents the input from being wrapped in a field
mutuallyExclusiveMutuallyExclusive (ref)falseConfiguration object to set if the input has a mutually exclusive opposing option
charCheckLimitobject <CharCheckLimit>falseSettings for a character counter or limit checker on the input
legendstringfalse (unless mutuallyExclusive is set)Text for the mutually exclusive fieldset‘s legend
legendClassesstringfalseClasses to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitlebooleantrue (unless legend is set)Creates an h1 inside the legend. Use when there is only a single fieldset on the page.
errorError (ref)falseConfiguration for validation errors
autocompletestringfalseThe HTML autocomplete attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholderbooleanfalseWill use the label provided as an accessible placeholder within the input
searchButtonobject <SearchButton>falseSettings for the search input button
postTextboxLinkTextstringfalseThe text for a link following the input
postTextboxLinkUrlstringfalseThe URL for the HTML href attribute of the link following the textbox
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
InputPrefix/InputSuffix
NameTypeRequiredDescription
textstringtrueThe visible text abbreviation for the prefix or suffix, for example, “cm“
titlestringfalseThe HTML title attribute for the <abbr> element, required if the visible text label is an abbreviation. Use to write out the long form of an abbreviated prefix or suffix. For example, if text is “€”, title should be “Euro (EUR)”.
idstringtrueThe HTML id of the <abbr> element used for the prefix or suffix. Used for the input’s aria-labelledby attribute.
CharCheckLimit
NameTypeRequiredDescription
idstringtrueThe HTML id of the component
limitintegertrueThe maximum number of characters allowed in the input
charCountOverLimitPluralstringtrueThe string displayed when user has entered more than one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} characters too many”.
charCountOverLimitSingularstringtrueThe string displayed when user has entered one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} character too many”.
charcheckCountdownbooleanfalseSet to “true” to show the character limit counter as characters are entered into the input
charCountPluralstringtrueThe string displayed when multiple characters can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} characters remaining”.
charCountSingularstringtrueThe string displayed when only one more character can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} character remaining”.
SearchButton
NameTypeRequiredDescription
textstringtrueText for the button label
typestringfalseSets the HTML type attribute for the <button>. Can be set to either: “submit” or “reset”. Defaults to “button”.
idstringfalseSets the HTML id attribute for the button
classesstringfalseClasses to add to the button component
iconTypestringfalseAdds an icon to the button, before the label, by setting the icon type
attributesobjectfalseHTML attributes (for example, data attributes) to add to the button component
HTML
<div class="ons-field">
  <label class="ons-label" for="number-example-input">Number of bedrooms</label>
  <input type="text" id="number-example-input"
    class="ons-input ons-input--text ons-input-type__input ons-input-number--w-2" pattern="[0-9]*" inputmode="numeric"
    autocomplete="off" min />
</div>

Variants

Input with description

An optional description parameter can be provided inside the label object to display a hint to help the user enter their information.

Example Input Text With Description contents

Nunjucks
{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "text-example-input-with-description",
        "label": {
            "text": "Enter some text",
            "description": "Example description hint text"
        }
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueThe HTML id of the input. Used for the label’s for attribute.
typestringfalseSets the HTML type attribute for the <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classesstringfalseClasses to add to the input
widthstringfalseRequired width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
namestringfalseThe HTML name attribute for the input
valuestring or integerfalseThe HTML value for the input to set a preset value for the field
minintegerfalseThe HTML min attribute to set the minimum accepted number or date for the input
maxintegerfalseThe HTML max attribute to set the maximum accepted number or date for the input
minLengthintegerfalseThe HTML minlength attribute to set the minimum accepted length of input value
maxLengthintegerfalseThe HTML maxlength attribute to set the maximum accepted length of input value
attributesobjectfalseHTML attributes (for example, data attributes) to add to the input
labelLabel (ref)falseSettings for the input label. for will automatically be set to match the input id
prefixobject <InputPrefix>falseSettings for the input prefix
suffixobject <InputSuffix>falseSettings for the input suffix
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalsePrevents the input from being wrapped in a field
mutuallyExclusiveMutuallyExclusive (ref)falseConfiguration object to set if the input has a mutually exclusive opposing option
charCheckLimitobject <CharCheckLimit>falseSettings for a character counter or limit checker on the input
legendstringfalse (unless mutuallyExclusive is set)Text for the mutually exclusive fieldset‘s legend
legendClassesstringfalseClasses to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitlebooleantrue (unless legend is set)Creates an h1 inside the legend. Use when there is only a single fieldset on the page.
errorError (ref)falseConfiguration for validation errors
autocompletestringfalseThe HTML autocomplete attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholderbooleanfalseWill use the label provided as an accessible placeholder within the input
searchButtonobject <SearchButton>falseSettings for the search input button
postTextboxLinkTextstringfalseThe text for a link following the input
postTextboxLinkUrlstringfalseThe URL for the HTML href attribute of the link following the textbox
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
InputPrefix/InputSuffix
NameTypeRequiredDescription
textstringtrueThe visible text abbreviation for the prefix or suffix, for example, “cm“
titlestringfalseThe HTML title attribute for the <abbr> element, required if the visible text label is an abbreviation. Use to write out the long form of an abbreviated prefix or suffix. For example, if text is “€”, title should be “Euro (EUR)”.
idstringtrueThe HTML id of the <abbr> element used for the prefix or suffix. Used for the input’s aria-labelledby attribute.
CharCheckLimit
NameTypeRequiredDescription
idstringtrueThe HTML id of the component
limitintegertrueThe maximum number of characters allowed in the input
charCountOverLimitPluralstringtrueThe string displayed when user has entered more than one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} characters too many”.
charCountOverLimitSingularstringtrueThe string displayed when user has entered one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} character too many”.
charcheckCountdownbooleanfalseSet to “true” to show the character limit counter as characters are entered into the input
charCountPluralstringtrueThe string displayed when multiple characters can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} characters remaining”.
charCountSingularstringtrueThe string displayed when only one more character can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} character remaining”.
SearchButton
NameTypeRequiredDescription
textstringtrueText for the button label
typestringfalseSets the HTML type attribute for the <button>. Can be set to either: “submit” or “reset”. Defaults to “button”.
idstringfalseSets the HTML id attribute for the button
classesstringfalseClasses to add to the button component
iconTypestringfalseAdds an icon to the button, before the label, by setting the icon type
attributesobjectfalseHTML attributes (for example, data attributes) to add to the button component
HTML
<div class="ons-field">
  <label class="ons-label ons-label--with-description" aria-describedby="description-hint"
    for="text-example-input-with-description">Enter some text</label>
  <span id="description-hint" class="ons-label__description  ons-input--with-description">Example description hint
    text</span>
  <input type="text" id="text-example-input-with-description" class="ons-input ons-input--text ons-input-type__input"
    aria-describedby="description-hint" />
</div>

Addresses

To collect addresses from a user, use the address input.

Postcodes

UK postcodes always consist of up to 7 letters and numbers and one optional space separating the outward and inward codes. A width of “7” letters will create a width appropriate to fit the widest potential postcode “WW4W 4WW”.

There is specific guidance on how to ask users for addresses.

Example Input Text Width Constrained contents

Nunjucks
{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "postcode",
        "width": "7",
        "autocomplete": "postal-code",
        "label": {
            "text": "Postcode"
        }
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueThe HTML id of the input. Used for the label’s for attribute.
typestringfalseSets the HTML type attribute for the <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classesstringfalseClasses to add to the input
widthstringfalseRequired width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
namestringfalseThe HTML name attribute for the input
valuestring or integerfalseThe HTML value for the input to set a preset value for the field
minintegerfalseThe HTML min attribute to set the minimum accepted number or date for the input
maxintegerfalseThe HTML max attribute to set the maximum accepted number or date for the input
minLengthintegerfalseThe HTML minlength attribute to set the minimum accepted length of input value
maxLengthintegerfalseThe HTML maxlength attribute to set the maximum accepted length of input value
attributesobjectfalseHTML attributes (for example, data attributes) to add to the input
labelLabel (ref)falseSettings for the input label. for will automatically be set to match the input id
prefixobject <InputPrefix>falseSettings for the input prefix
suffixobject <InputSuffix>falseSettings for the input suffix
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalsePrevents the input from being wrapped in a field
mutuallyExclusiveMutuallyExclusive (ref)falseConfiguration object to set if the input has a mutually exclusive opposing option
charCheckLimitobject <CharCheckLimit>falseSettings for a character counter or limit checker on the input
legendstringfalse (unless mutuallyExclusive is set)Text for the mutually exclusive fieldset‘s legend
legendClassesstringfalseClasses to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitlebooleantrue (unless legend is set)Creates an h1 inside the legend. Use when there is only a single fieldset on the page.
errorError (ref)falseConfiguration for validation errors
autocompletestringfalseThe HTML autocomplete attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholderbooleanfalseWill use the label provided as an accessible placeholder within the input
searchButtonobject <SearchButton>falseSettings for the search input button
postTextboxLinkTextstringfalseThe text for a link following the input
postTextboxLinkUrlstringfalseThe URL for the HTML href attribute of the link following the textbox
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
InputPrefix/InputSuffix
NameTypeRequiredDescription
textstringtrueThe visible text abbreviation for the prefix or suffix, for example, “cm“
titlestringfalseThe HTML title attribute for the <abbr> element, required if the visible text label is an abbreviation. Use to write out the long form of an abbreviated prefix or suffix. For example, if text is “€”, title should be “Euro (EUR)”.
idstringtrueThe HTML id of the <abbr> element used for the prefix or suffix. Used for the input’s aria-labelledby attribute.
CharCheckLimit
NameTypeRequiredDescription
idstringtrueThe HTML id of the component
limitintegertrueThe maximum number of characters allowed in the input
charCountOverLimitPluralstringtrueThe string displayed when user has entered more than one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} characters too many”.
charCountOverLimitSingularstringtrueThe string displayed when user has entered one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} character too many”.
charcheckCountdownbooleanfalseSet to “true” to show the character limit counter as characters are entered into the input
charCountPluralstringtrueThe string displayed when multiple characters can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} characters remaining”.
charCountSingularstringtrueThe string displayed when only one more character can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} character remaining”.
SearchButton
NameTypeRequiredDescription
textstringtrueText for the button label
typestringfalseSets the HTML type attribute for the <button>. Can be set to either: “submit” or “reset”. Defaults to “button”.
idstringfalseSets the HTML id attribute for the button
classesstringfalseClasses to add to the button component
iconTypestringfalseAdds an icon to the button, before the label, by setting the icon type
attributesobjectfalseHTML attributes (for example, data attributes) to add to the button component
HTML
<div class="ons-field">
  <label class="ons-label" for="postcode">Postcode</label>
  <input type="text" id="postcode" class="ons-input ons-input--text ons-input-type__input ons-input--w-7"
    autocomplete="postal-code" />
</div>

Email

There is specific guidance on how to ask users for email addresses.

Setting type to “email” will bring up the correct keypad on touch devices.

Example Input Email contents

Nunjucks
{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "email-example-input-email",
        "type": "email",
        "autocomplete": "email",
        "label": {
            "text": "Email address",
            "description": "This will not be stored and only used once to send your confirmation"
        }
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueThe HTML id of the input. Used for the label’s for attribute.
typestringfalseSets the HTML type attribute for the <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classesstringfalseClasses to add to the input
widthstringfalseRequired width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
namestringfalseThe HTML name attribute for the input
valuestring or integerfalseThe HTML value for the input to set a preset value for the field
minintegerfalseThe HTML min attribute to set the minimum accepted number or date for the input
maxintegerfalseThe HTML max attribute to set the maximum accepted number or date for the input
minLengthintegerfalseThe HTML minlength attribute to set the minimum accepted length of input value
maxLengthintegerfalseThe HTML maxlength attribute to set the maximum accepted length of input value
attributesobjectfalseHTML attributes (for example, data attributes) to add to the input
labelLabel (ref)falseSettings for the input label. for will automatically be set to match the input id
prefixobject <InputPrefix>falseSettings for the input prefix
suffixobject <InputSuffix>falseSettings for the input suffix
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalsePrevents the input from being wrapped in a field
mutuallyExclusiveMutuallyExclusive (ref)falseConfiguration object to set if the input has a mutually exclusive opposing option
charCheckLimitobject <CharCheckLimit>falseSettings for a character counter or limit checker on the input
legendstringfalse (unless mutuallyExclusive is set)Text for the mutually exclusive fieldset‘s legend
legendClassesstringfalseClasses to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitlebooleantrue (unless legend is set)Creates an h1 inside the legend. Use when there is only a single fieldset on the page.
errorError (ref)falseConfiguration for validation errors
autocompletestringfalseThe HTML autocomplete attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholderbooleanfalseWill use the label provided as an accessible placeholder within the input
searchButtonobject <SearchButton>falseSettings for the search input button
postTextboxLinkTextstringfalseThe text for a link following the input
postTextboxLinkUrlstringfalseThe URL for the HTML href attribute of the link following the textbox
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
InputPrefix/InputSuffix
NameTypeRequiredDescription
textstringtrueThe visible text abbreviation for the prefix or suffix, for example, “cm“
titlestringfalseThe HTML title attribute for the <abbr> element, required if the visible text label is an abbreviation. Use to write out the long form of an abbreviated prefix or suffix. For example, if text is “€”, title should be “Euro (EUR)”.
idstringtrueThe HTML id of the <abbr> element used for the prefix or suffix. Used for the input’s aria-labelledby attribute.
CharCheckLimit
NameTypeRequiredDescription
idstringtrueThe HTML id of the component
limitintegertrueThe maximum number of characters allowed in the input
charCountOverLimitPluralstringtrueThe string displayed when user has entered more than one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} characters too many”.
charCountOverLimitSingularstringtrueThe string displayed when user has entered one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} character too many”.
charcheckCountdownbooleanfalseSet to “true” to show the character limit counter as characters are entered into the input
charCountPluralstringtrueThe string displayed when multiple characters can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} characters remaining”.
charCountSingularstringtrueThe string displayed when only one more character can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} character remaining”.
SearchButton
NameTypeRequiredDescription
textstringtrueText for the button label
typestringfalseSets the HTML type attribute for the <button>. Can be set to either: “submit” or “reset”. Defaults to “button”.
idstringfalseSets the HTML id attribute for the button
classesstringfalseClasses to add to the button component
iconTypestringfalseAdds an icon to the button, before the label, by setting the icon type
attributesobjectfalseHTML attributes (for example, data attributes) to add to the button component
HTML
<div class="ons-field">
  <label class="ons-label ons-label--with-description" aria-describedby="description-hint"
    for="email-example-input-email">Email address</label>
  <span id="description-hint" class="ons-label__description  ons-input--with-description">This will not be stored and
    only used once to send your confirmation</span>
  <input type="email" id="email-example-input-email" class="ons-input ons-input--text ons-input-type__input"
    autocomplete="email" aria-describedby="description-hint" />
</div>

Telephone

There is specific guidance on how to ask users for phone numbers.

Setting type to “tel” will bring up the correct keypad on touch devices.

Example Input Telephone contents

Nunjucks
{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "telephone",
        "type": "tel",
        "autocomplete": "tel",
        "width": "15",
        "label": {
            "text": "UK mobile number",
            "description": "This will not be stored and only used once to send your access code"
        }
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueThe HTML id of the input. Used for the label’s for attribute.
typestringfalseSets the HTML type attribute for the <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classesstringfalseClasses to add to the input
widthstringfalseRequired width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
namestringfalseThe HTML name attribute for the input
valuestring or integerfalseThe HTML value for the input to set a preset value for the field
minintegerfalseThe HTML min attribute to set the minimum accepted number or date for the input
maxintegerfalseThe HTML max attribute to set the maximum accepted number or date for the input
minLengthintegerfalseThe HTML minlength attribute to set the minimum accepted length of input value
maxLengthintegerfalseThe HTML maxlength attribute to set the maximum accepted length of input value
attributesobjectfalseHTML attributes (for example, data attributes) to add to the input
labelLabel (ref)falseSettings for the input label. for will automatically be set to match the input id
prefixobject <InputPrefix>falseSettings for the input prefix
suffixobject <InputSuffix>falseSettings for the input suffix
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalsePrevents the input from being wrapped in a field
mutuallyExclusiveMutuallyExclusive (ref)falseConfiguration object to set if the input has a mutually exclusive opposing option
charCheckLimitobject <CharCheckLimit>falseSettings for a character counter or limit checker on the input
legendstringfalse (unless mutuallyExclusive is set)Text for the mutually exclusive fieldset‘s legend
legendClassesstringfalseClasses to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitlebooleantrue (unless legend is set)Creates an h1 inside the legend. Use when there is only a single fieldset on the page.
errorError (ref)falseConfiguration for validation errors
autocompletestringfalseThe HTML autocomplete attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholderbooleanfalseWill use the label provided as an accessible placeholder within the input
searchButtonobject <SearchButton>falseSettings for the search input button
postTextboxLinkTextstringfalseThe text for a link following the input
postTextboxLinkUrlstringfalseThe URL for the HTML href attribute of the link following the textbox
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
InputPrefix/InputSuffix
NameTypeRequiredDescription
textstringtrueThe visible text abbreviation for the prefix or suffix, for example, “cm“
titlestringfalseThe HTML title attribute for the <abbr> element, required if the visible text label is an abbreviation. Use to write out the long form of an abbreviated prefix or suffix. For example, if text is “€”, title should be “Euro (EUR)”.
idstringtrueThe HTML id of the <abbr> element used for the prefix or suffix. Used for the input’s aria-labelledby attribute.
CharCheckLimit
NameTypeRequiredDescription
idstringtrueThe HTML id of the component
limitintegertrueThe maximum number of characters allowed in the input
charCountOverLimitPluralstringtrueThe string displayed when user has entered more than one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} characters too many”.
charCountOverLimitSingularstringtrueThe string displayed when user has entered one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} character too many”.
charcheckCountdownbooleanfalseSet to “true” to show the character limit counter as characters are entered into the input
charCountPluralstringtrueThe string displayed when multiple characters can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} characters remaining”.
charCountSingularstringtrueThe string displayed when only one more character can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} character remaining”.
SearchButton
NameTypeRequiredDescription
textstringtrueText for the button label
typestringfalseSets the HTML type attribute for the <button>. Can be set to either: “submit” or “reset”. Defaults to “button”.
idstringfalseSets the HTML id attribute for the button
classesstringfalseClasses to add to the button component
iconTypestringfalseAdds an icon to the button, before the label, by setting the icon type
attributesobjectfalseHTML attributes (for example, data attributes) to add to the button component
HTML
<div class="ons-field">
  <label class="ons-label ons-label--with-description" aria-describedby="description-hint" for="telephone">UK mobile
    number</label>
  <span id="description-hint" class="ons-label__description  ons-input--with-description">This will not be stored and
    only used once to send your access code</span>
  <input type="tel" id="telephone" class="ons-input ons-input--text ons-input-type__input ons-input-number--w-15"
    autocomplete="tel" aria-describedby="description-hint" />
</div>

Number

There is specific guidance on how to ask users for numeric values.

Setting the type parameter to “number” will set the HTML attributes inputmode and pattern to bring up the correct keypad on touch devices.

When you are using a description as well as a label on financial inputs, use:

"Enter a value to the nearest thousand. For example, 56,000."

Do not use symbols in combination with text. For example, "£thousand".

Important information:

The HTML type attribute will be set to “text” rather than “number” due to an issue with Firefox and Safari not blocking non-numeric characters.

For more information, see the Bugzilla entry on Safari and Firefox blocking non-numeric characters (opens in a new tab) 

Example Input Number Prefixed contents

Nunjucks
{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "prefixed",
        "type": "number",
        "width": "6",
        "autocomplete": "off",
        "label": {
            "text": "Your annual salary before taxes"
        },
        "prefix": {
            "title": "British pounds (GBP)",
            "text": "£",
            "id": "annual-salary-gpb-prefix"
        }
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueThe HTML id of the input. Used for the label’s for attribute.
typestringfalseSets the HTML type attribute for the <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classesstringfalseClasses to add to the input
widthstringfalseRequired width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
namestringfalseThe HTML name attribute for the input
valuestring or integerfalseThe HTML value for the input to set a preset value for the field
minintegerfalseThe HTML min attribute to set the minimum accepted number or date for the input
maxintegerfalseThe HTML max attribute to set the maximum accepted number or date for the input
minLengthintegerfalseThe HTML minlength attribute to set the minimum accepted length of input value
maxLengthintegerfalseThe HTML maxlength attribute to set the maximum accepted length of input value
attributesobjectfalseHTML attributes (for example, data attributes) to add to the input
labelLabel (ref)falseSettings for the input label. for will automatically be set to match the input id
prefixobject <InputPrefix>falseSettings for the input prefix
suffixobject <InputSuffix>falseSettings for the input suffix
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalsePrevents the input from being wrapped in a field
mutuallyExclusiveMutuallyExclusive (ref)falseConfiguration object to set if the input has a mutually exclusive opposing option
charCheckLimitobject <CharCheckLimit>falseSettings for a character counter or limit checker on the input
legendstringfalse (unless mutuallyExclusive is set)Text for the mutually exclusive fieldset‘s legend
legendClassesstringfalseClasses to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitlebooleantrue (unless legend is set)Creates an h1 inside the legend. Use when there is only a single fieldset on the page.
errorError (ref)falseConfiguration for validation errors
autocompletestringfalseThe HTML autocomplete attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholderbooleanfalseWill use the label provided as an accessible placeholder within the input
searchButtonobject <SearchButton>falseSettings for the search input button
postTextboxLinkTextstringfalseThe text for a link following the input
postTextboxLinkUrlstringfalseThe URL for the HTML href attribute of the link following the textbox
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
InputPrefix/InputSuffix
NameTypeRequiredDescription
textstringtrueThe visible text abbreviation for the prefix or suffix, for example, “cm“
titlestringfalseThe HTML title attribute for the <abbr> element, required if the visible text label is an abbreviation. Use to write out the long form of an abbreviated prefix or suffix. For example, if text is “€”, title should be “Euro (EUR)”.
idstringtrueThe HTML id of the <abbr> element used for the prefix or suffix. Used for the input’s aria-labelledby attribute.
CharCheckLimit
NameTypeRequiredDescription
idstringtrueThe HTML id of the component
limitintegertrueThe maximum number of characters allowed in the input
charCountOverLimitPluralstringtrueThe string displayed when user has entered more than one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} characters too many”.
charCountOverLimitSingularstringtrueThe string displayed when user has entered one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} character too many”.
charcheckCountdownbooleanfalseSet to “true” to show the character limit counter as characters are entered into the input
charCountPluralstringtrueThe string displayed when multiple characters can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} characters remaining”.
charCountSingularstringtrueThe string displayed when only one more character can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} character remaining”.
SearchButton
NameTypeRequiredDescription
textstringtrueText for the button label
typestringfalseSets the HTML type attribute for the <button>. Can be set to either: “submit” or “reset”. Defaults to “button”.
idstringfalseSets the HTML id attribute for the button
classesstringfalseClasses to add to the button component
iconTypestringfalseAdds an icon to the button, before the label, by setting the icon type
attributesobjectfalseHTML attributes (for example, data attributes) to add to the button component
HTML
<div class="ons-field">
  <label class="ons-label" for="prefixed">Your annual salary before taxes</label>
  <span class="ons-input-type ons-input-type--prefix ons-js-input-container-abbr">
    <span class="ons-input-type__inner">
      <input type="text" id="prefixed" class="ons-input ons-input--text ons-input-type__input ons-input-number--w-6"
        aria-labelledby="prefixed annual-salary-gpb-prefix" pattern="[0-9]*" inputmode="numeric" autocomplete="off" />
      <abbr id="annual-salary-gpb-prefix" class="ons-input-type__type ons-js-input-abbr"
        aria-label="British pounds (GBP)" role="figure" title="British pounds (GBP)">£</abbr>
    </span>
  </span>
</div>

Character limit checker

Use this for client-side validation of inputs that need character limits due to data size restrictions.

Warning:

Use this variant as little as possible. Users do not expect a limit on inputs, and often do not look up from a keyboard as they type. This means they may not notice the counter.

The character limit counter is displayed when the limit is exceeded. Set the charCheckLimit object with the limit, charCountOverLimitSingular and charCountOverLimitPlural parameters.

Example Input Text Width Constrained contents

Nunjucks
{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "postcode",
        "width": "7",
        "autocomplete": "postal-code",
        "label": {
            "text": "Postcode"
        }
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueThe HTML id of the input. Used for the label’s for attribute.
typestringfalseSets the HTML type attribute for the <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classesstringfalseClasses to add to the input
widthstringfalseRequired width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
namestringfalseThe HTML name attribute for the input
valuestring or integerfalseThe HTML value for the input to set a preset value for the field
minintegerfalseThe HTML min attribute to set the minimum accepted number or date for the input
maxintegerfalseThe HTML max attribute to set the maximum accepted number or date for the input
minLengthintegerfalseThe HTML minlength attribute to set the minimum accepted length of input value
maxLengthintegerfalseThe HTML maxlength attribute to set the maximum accepted length of input value
attributesobjectfalseHTML attributes (for example, data attributes) to add to the input
labelLabel (ref)falseSettings for the input label. for will automatically be set to match the input id
prefixobject <InputPrefix>falseSettings for the input prefix
suffixobject <InputSuffix>falseSettings for the input suffix
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalsePrevents the input from being wrapped in a field
mutuallyExclusiveMutuallyExclusive (ref)falseConfiguration object to set if the input has a mutually exclusive opposing option
charCheckLimitobject <CharCheckLimit>falseSettings for a character counter or limit checker on the input
legendstringfalse (unless mutuallyExclusive is set)Text for the mutually exclusive fieldset‘s legend
legendClassesstringfalseClasses to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitlebooleantrue (unless legend is set)Creates an h1 inside the legend. Use when there is only a single fieldset on the page.
errorError (ref)falseConfiguration for validation errors
autocompletestringfalseThe HTML autocomplete attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholderbooleanfalseWill use the label provided as an accessible placeholder within the input
searchButtonobject <SearchButton>falseSettings for the search input button
postTextboxLinkTextstringfalseThe text for a link following the input
postTextboxLinkUrlstringfalseThe URL for the HTML href attribute of the link following the textbox
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
InputPrefix/InputSuffix
NameTypeRequiredDescription
textstringtrueThe visible text abbreviation for the prefix or suffix, for example, “cm“
titlestringfalseThe HTML title attribute for the <abbr> element, required if the visible text label is an abbreviation. Use to write out the long form of an abbreviated prefix or suffix. For example, if text is “€”, title should be “Euro (EUR)”.
idstringtrueThe HTML id of the <abbr> element used for the prefix or suffix. Used for the input’s aria-labelledby attribute.
CharCheckLimit
NameTypeRequiredDescription
idstringtrueThe HTML id of the component
limitintegertrueThe maximum number of characters allowed in the input
charCountOverLimitPluralstringtrueThe string displayed when user has entered more than one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} characters too many”.
charCountOverLimitSingularstringtrueThe string displayed when user has entered one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} character too many”.
charcheckCountdownbooleanfalseSet to “true” to show the character limit counter as characters are entered into the input
charCountPluralstringtrueThe string displayed when multiple characters can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} characters remaining”.
charCountSingularstringtrueThe string displayed when only one more character can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} character remaining”.
SearchButton
NameTypeRequiredDescription
textstringtrueText for the button label
typestringfalseSets the HTML type attribute for the <button>. Can be set to either: “submit” or “reset”. Defaults to “button”.
idstringfalseSets the HTML id attribute for the button
classesstringfalseClasses to add to the button component
iconTypestringfalseAdds an icon to the button, before the label, by setting the icon type
attributesobjectfalseHTML attributes (for example, data attributes) to add to the button component
HTML
<div class="ons-field">
  <label class="ons-label" for="postcode">Postcode</label>
  <input type="text" id="postcode" class="ons-input ons-input--text ons-input-type__input ons-input--w-7"
    autocomplete="postal-code" />
</div>

Use the searchButton parameter to allow a user to search for a page.

To create an accessible placeholder for the input, provide accessiblePlaceholder: true and a label.

Example Input Search With Placeholder contents

Nunjucks
{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": 'search-field',
        "label": {
            "text": 'Search this service'
        },
        "accessiblePlaceholder": true,
        "searchButton": {
            "visuallyHideButtonText": true,
            "text": 'Search',
            "iconType": 'search'
        }
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueThe HTML id of the input. Used for the label’s for attribute.
typestringfalseSets the HTML type attribute for the <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classesstringfalseClasses to add to the input
widthstringfalseRequired width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
namestringfalseThe HTML name attribute for the input
valuestring or integerfalseThe HTML value for the input to set a preset value for the field
minintegerfalseThe HTML min attribute to set the minimum accepted number or date for the input
maxintegerfalseThe HTML max attribute to set the maximum accepted number or date for the input
minLengthintegerfalseThe HTML minlength attribute to set the minimum accepted length of input value
maxLengthintegerfalseThe HTML maxlength attribute to set the maximum accepted length of input value
attributesobjectfalseHTML attributes (for example, data attributes) to add to the input
labelLabel (ref)falseSettings for the input label. for will automatically be set to match the input id
prefixobject <InputPrefix>falseSettings for the input prefix
suffixobject <InputSuffix>falseSettings for the input suffix
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalsePrevents the input from being wrapped in a field
mutuallyExclusiveMutuallyExclusive (ref)falseConfiguration object to set if the input has a mutually exclusive opposing option
charCheckLimitobject <CharCheckLimit>falseSettings for a character counter or limit checker on the input
legendstringfalse (unless mutuallyExclusive is set)Text for the mutually exclusive fieldset‘s legend
legendClassesstringfalseClasses to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitlebooleantrue (unless legend is set)Creates an h1 inside the legend. Use when there is only a single fieldset on the page.
errorError (ref)falseConfiguration for validation errors
autocompletestringfalseThe HTML autocomplete attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholderbooleanfalseWill use the label provided as an accessible placeholder within the input
searchButtonobject <SearchButton>falseSettings for the search input button
postTextboxLinkTextstringfalseThe text for a link following the input
postTextboxLinkUrlstringfalseThe URL for the HTML href attribute of the link following the textbox
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
InputPrefix/InputSuffix
NameTypeRequiredDescription
textstringtrueThe visible text abbreviation for the prefix or suffix, for example, “cm“
titlestringfalseThe HTML title attribute for the <abbr> element, required if the visible text label is an abbreviation. Use to write out the long form of an abbreviated prefix or suffix. For example, if text is “€”, title should be “Euro (EUR)”.
idstringtrueThe HTML id of the <abbr> element used for the prefix or suffix. Used for the input’s aria-labelledby attribute.
CharCheckLimit
NameTypeRequiredDescription
idstringtrueThe HTML id of the component
limitintegertrueThe maximum number of characters allowed in the input
charCountOverLimitPluralstringtrueThe string displayed when user has entered more than one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} characters too many”.
charCountOverLimitSingularstringtrueThe string displayed when user has entered one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} character too many”.
charcheckCountdownbooleanfalseSet to “true” to show the character limit counter as characters are entered into the input
charCountPluralstringtrueThe string displayed when multiple characters can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} characters remaining”.
charCountSingularstringtrueThe string displayed when only one more character can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} character remaining”.
SearchButton
NameTypeRequiredDescription
textstringtrueText for the button label
typestringfalseSets the HTML type attribute for the <button>. Can be set to either: “submit” or “reset”. Defaults to “button”.
idstringfalseSets the HTML id attribute for the button
classesstringfalseClasses to add to the button component
iconTypestringfalseAdds an icon to the button, before the label, by setting the icon type
attributesobjectfalseHTML attributes (for example, data attributes) to add to the button component
HTML
<div class="ons-field">
  <span class="ons-grid--flex  ons-input_search-button">
    <label class="ons-label ons-label--placeholder" for="search-field">Search this service</label>
    <input type="search" id="search-field"
      class="ons-input ons-input--text ons-input-type__input ons-search__input ons-input--placeholder"
      placeholder="Search this service" />
    <button type="submit" class="ons-btn ons-search__btn ons-btn--small">
      <span class="ons-btn__inner"><svg class="ons-icon" viewBox="0 0 12 12" xmlns="http://www.w3.org/2000/svg"
          aria-hidden="true" fill="currentColor">
          <path
            d="M11.86 10.23 8.62 6.99a4.63 4.63 0 1 0-6.34 1.64 4.55 4.55 0 0 0 2.36.64 4.65 4.65 0 0 0 2.33-.65l3.24 3.23a.46.46 0 0 0 .65 0l1-1a.48.48 0 0 0 0-.62Zm-5-3.32a3.28 3.28 0 0 1-2.31.93 3.22 3.22 0 1 1 2.35-.93Z" />
        </svg><span class="ons-btn__text ons-u-vh@xxs@s"><span class="ons-u-vh">Search</span></span>
      </span>
    </button>
  </span>
</div>

The character check counter is displayed when the charCheckLimit object is included with params: limit, charCountOverLimitSingular, charCountOverLimitPlural, charCountPlural and charCountSingular parameters are defined.

The button is disabled until the length of the input value matches the value supplied to the limit param.

Example Input Search With Character Check contents

Nunjucks
{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": 'search-field',
        "label": {
            'text': 'Filter results',
            "classes": 'ons-u-pb-xxs ons-u-mb-no'
        },
        "searchButton": {
            "text": 'Filter'
        },
        "width": "10",
        "charCheckLimit": {
            "charcheckCountdown": true,
            "limit": 10,
            "charCountSingular": "{x} more character needed",
            "charCountPlural": "{x} more characters needed",
            "charCountOverLimitSingular": "{x} character too many",
            "charCountOverLimitPlural": "{x} characters too many"
        }
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueThe HTML id of the input. Used for the label’s for attribute.
typestringfalseSets the HTML type attribute for the <input>. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classesstringfalseClasses to add to the input
widthstringfalseRequired width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
namestringfalseThe HTML name attribute for the input
valuestring or integerfalseThe HTML value for the input to set a preset value for the field
minintegerfalseThe HTML min attribute to set the minimum accepted number or date for the input
maxintegerfalseThe HTML max attribute to set the maximum accepted number or date for the input
minLengthintegerfalseThe HTML minlength attribute to set the minimum accepted length of input value
maxLengthintegerfalseThe HTML maxlength attribute to set the maximum accepted length of input value
attributesobjectfalseHTML attributes (for example, data attributes) to add to the input
labelLabel (ref)falseSettings for the input label. for will automatically be set to match the input id
prefixobject <InputPrefix>falseSettings for the input prefix
suffixobject <InputSuffix>falseSettings for the input suffix
fieldIdstringfalseThe HTML id of the field
fieldClassesstringfalseClasses to add to the field
dontWrapbooleanfalsePrevents the input from being wrapped in a field
mutuallyExclusiveMutuallyExclusive (ref)falseConfiguration object to set if the input has a mutually exclusive opposing option
charCheckLimitobject <CharCheckLimit>falseSettings for a character counter or limit checker on the input
legendstringfalse (unless mutuallyExclusive is set)Text for the mutually exclusive fieldset‘s legend
legendClassesstringfalseClasses to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitlebooleantrue (unless legend is set)Creates an h1 inside the legend. Use when there is only a single fieldset on the page.
errorError (ref)falseConfiguration for validation errors
autocompletestringfalseThe HTML autocomplete attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholderbooleanfalseWill use the label provided as an accessible placeholder within the input
searchButtonobject <SearchButton>falseSettings for the search input button
postTextboxLinkTextstringfalseThe text for a link following the input
postTextboxLinkUrlstringfalseThe URL for the HTML href attribute of the link following the textbox
listenersobjectfalseCreates a script element that adds an event listener to the element by id. Takes key { event } and value { function }
InputPrefix/InputSuffix
NameTypeRequiredDescription
textstringtrueThe visible text abbreviation for the prefix or suffix, for example, “cm“
titlestringfalseThe HTML title attribute for the <abbr> element, required if the visible text label is an abbreviation. Use to write out the long form of an abbreviated prefix or suffix. For example, if text is “€”, title should be “Euro (EUR)”.
idstringtrueThe HTML id of the <abbr> element used for the prefix or suffix. Used for the input’s aria-labelledby attribute.
CharCheckLimit
NameTypeRequiredDescription
idstringtrueThe HTML id of the component
limitintegertrueThe maximum number of characters allowed in the input
charCountOverLimitPluralstringtrueThe string displayed when user has entered more than one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} characters too many”.
charCountOverLimitSingularstringtrueThe string displayed when user has entered one character over the set limit. Set {x} in the string to be replaced with the number of characters, for example “{x} character too many”.
charcheckCountdownbooleanfalseSet to “true” to show the character limit counter as characters are entered into the input
charCountPluralstringtrueThe string displayed when multiple characters can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} characters remaining”.
charCountSingularstringtrueThe string displayed when only one more character can be entered before the limit is reached. Set {x} in the string to be replaced with the number, for example “You have {x} character remaining”.
SearchButton
NameTypeRequiredDescription
textstringtrueText for the button label
typestringfalseSets the HTML type attribute for the <button>. Can be set to either: “submit” or “reset”. Defaults to “button”.
idstringfalseSets the HTML id attribute for the button
classesstringfalseClasses to add to the button component
iconTypestringfalseAdds an icon to the button, before the label, by setting the icon type
attributesobjectfalseHTML attributes (for example, data attributes) to add to the button component
HTML
<div class="ons-field">
  <span class="ons-js-char-check-input">
    <label class="ons-label ons-u-pb-xxs ons-u-mb-no" for="search-field">Filter results</label>
    <span class="ons-grid--flex  ons-input_search-button">
      <input type="search" id="search-field"
        class="ons-input ons-input--text ons-input-type__input ons-search__input ons-input--w-10"
        data-char-check-ref="search-field-check" data-char-check-num="10" aria-describedby="search-field-check"
        data-char-check-countdown="true" />
      <button type="submit" class="ons-btn ons-search__btn ons-btn--small">
        <span class="ons-btn__inner"><span class="ons-btn__text">Filter</span>
        </span>
      </button>
    </span>
  </span>
  <span id="search-field-check" class="ons-input__limit ons-u-fs-s--b ons-u-d-no ons-u-mt-xs"
    data-charcount-singular="{x} more character needed" data-charcount-plural="{x} more characters needed"
    data-charcount-limit-singular="{x} character too many" data-charcount-limit-plural="{x} characters too many">
  </span>
</div>

How to check an input field

To help users enter something valid into an input field, you should:

  • allow them to paste into the input field
  • check they have entered something in the input field
  • check that what they have entered is valid
  • show an error message if they have not entered anything or what they have entered is not valid

Error messages

To show the error details above the input field, use the correct errors pattern.

Example Input Email With Error contents

Nunjucks
{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "email-example-input-email-with-error",
        "type": "email",
        "autocomplete": "email",
        "value": "name.com",
        "label": {
            "text": "Email address",
            "description": "This will not be stored and only used once to send your confirmation"
        },
        "error": {
            "id": "email-error-example-input-email-with-error",
            "text": "Enter an email address in a valid format, for example, name@example.com"
        }
    })
}}
HTML
<div class="ons-panel ons-panel--error ons-panel--no-title" id="email-error-example-input-email-with-error">
  <span class="ons-panel__assistive-text ons-u-vh">Error: </span>
  <div class="ons-panel__body">
    <p class="ons-panel__error">
      <strong>Enter an email address in a valid format, for example, name@example.com</strong>
    </p>
    <div class="ons-field">
      <label class="ons-label ons-label--with-description" aria-describedby="description-hint"
        for="email-example-input-email-with-error">Email address</label>
      <span id="description-hint" class="ons-label__description  ons-input--with-description">This will not be stored
        and only used once to send your confirmation</span>
      <input type="email" id="email-example-input-email-with-error"
        class="ons-input ons-input--text ons-input-type__input ons-input--error" value="name.com" autocomplete="email"
        aria-describedby="description-hint" />
    </div>
  </div>
</div>

Empty input fields

Use “Enter [whatever the input is]”.
For example, “Enter an email address”.

Invalid formatting

Use “Enter [whatever the input is] in a valid format, for example, [whatever the example is]”.
For example, “Enter an email address in a valid format, for example, name@example.com”.

Warning:

Only use an example if it is appropriate. For security reasons, it may not be appropriate to give an example of an access code.

There is specific guidance on how to ask users for access codes.

Research on this component

Between February and September 2020, during research for Census 2021, we tested the character limit checker.

We found that users:

  • may not notice the character counter when looking down at the keyboard
  • expect to be stopped from entering too many characters

Help improve this page

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