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

Nunjucksfor Example Input Text
Nunjucks macro optionsfor Example Input Text
HTMLfor Example Input Text

Nunjucks

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

Nunjucks macro options

Name	Type	Required	Description
id	string	true	The HTML `id` of the input. Used for the label’s `for` attribute.
type	string	false	Sets the HTML `type` attribute for the `<input>`. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classes	string	false	Classes to add to the input
width	string	false	Required width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
name	string	false	The HTML `name` attribute for the input
value	string or integer	false	The HTML `value` for the input to set a preset value for the field
min	integer	false	The HTML `min` attribute to set the minimum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
minLength	integer	false	The HTML `minlength` attribute to set the minimum accepted length of input value
maxLength	integer	false	The HTML `maxlength` attribute to set the maximum accepted length of input value
attributes	object	false	HTML attributes (for example, data attributes) to add to the input
label	`Label` (ref)	false	Settings for the input label. `for` will automatically be set to match the input id
prefix	object `<InputPrefix>`	false	Settings for the input prefix
suffix	object `<InputSuffix>`	false	Settings for the input suffix
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes to add to the field
dontWrap	boolean	false	Prevents the input from being wrapped in a field
mutuallyExclusive	`MutuallyExclusive` (ref)	false	Configuration object to set if the input has a mutually exclusive opposing option
charCheckLimit	object `<CharCheckLimit>`	false	Settings for a character counter or limit checker on the input
legend	string	false (unless `mutuallyExclusive` is set)	Text for the mutually exclusive fieldset‘s legend
legendClasses	string	false	Classes to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitle	boolean	true (unless `legend` is set)	Creates an `h1` inside the `legend`. Use when there is only a single fieldset on the page.
error	`Error` (ref)	false	Configuration for validation errors
autocomplete	string	false	The HTML `autocomplete` attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholder	boolean	false	Will use the label provided as an accessible placeholder within the input
searchButton	object `<SearchButton>`	false	Settings for the search input button
postTextboxLinkText	string	false	The text for a link following the input
postTextboxLinkUrl	string	false	The URL for the HTML `href` attribute of the link following the textbox
listeners	object	false	Creates a `script` element that adds an event listener to the element by `id`. Takes `key { event }` and `value { function }`

InputPrefix/InputSuffix
Name	Type	Required	Description
text	string	true	The visible text abbreviation for the prefix or suffix, for example, “cm“
title	string	false	The 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)”.
id	string	true	The HTML `id` of the `<abbr>` element used for the prefix or suffix. Used for the input’s `aria-labelledby` attribute.

CharCheckLimit
Name	Type	Required	Description
id	string	true	The HTML `id` of the component
limit	integer	true	The maximum number of characters allowed in the input
charCountOverLimitPlural	string	true	The 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”.
charCountOverLimitSingular	string	true	The 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”.
charcheckCountdown	boolean	false	Set to “true” to show the character limit counter as characters are entered into the input
charCountPlural	string	true	The 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”.
charCountSingular	string	true	The 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
Name	Type	Required	Description
text	string	true	Text for the button label
type	string	false	Sets the HTML `type` attribute for the `<button>`. Can be set to either: “submit” or “reset”. Defaults to “button”.
id	string	false	Sets the HTML `id` attribute for the button
classes	string	false	Classes to add to the button component
iconType	string	false	Adds an icon to the button, before the label, by setting the icon type
attributes	object	false	HTML 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

Nunjucksfor Example Input Number
Nunjucks macro optionsfor Example Input Number
HTMLfor Example Input Number

Nunjucks

{% from "components/input/_macro.njk" import onsInput %}

{{
    onsInput({
        "id": "number-example-input",
        "type": "number",
        "width": "2",
        "autocomplete": "off",
        "label": {
            "text": "Number of bedrooms"
        }
    })
}}

Nunjucks macro options

Name	Type	Required	Description
id	string	true	The HTML `id` of the input. Used for the label’s `for` attribute.
type	string	false	Sets the HTML `type` attribute for the `<input>`. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classes	string	false	Classes to add to the input
width	string	false	Required width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
name	string	false	The HTML `name` attribute for the input
value	string or integer	false	The HTML `value` for the input to set a preset value for the field
min	integer	false	The HTML `min` attribute to set the minimum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
minLength	integer	false	The HTML `minlength` attribute to set the minimum accepted length of input value
maxLength	integer	false	The HTML `maxlength` attribute to set the maximum accepted length of input value
attributes	object	false	HTML attributes (for example, data attributes) to add to the input
label	`Label` (ref)	false	Settings for the input label. `for` will automatically be set to match the input id
prefix	object `<InputPrefix>`	false	Settings for the input prefix
suffix	object `<InputSuffix>`	false	Settings for the input suffix
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes to add to the field
dontWrap	boolean	false	Prevents the input from being wrapped in a field
mutuallyExclusive	`MutuallyExclusive` (ref)	false	Configuration object to set if the input has a mutually exclusive opposing option
charCheckLimit	object `<CharCheckLimit>`	false	Settings for a character counter or limit checker on the input
legend	string	false (unless `mutuallyExclusive` is set)	Text for the mutually exclusive fieldset‘s legend
legendClasses	string	false	Classes to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitle	boolean	true (unless `legend` is set)	Creates an `h1` inside the `legend`. Use when there is only a single fieldset on the page.
error	`Error` (ref)	false	Configuration for validation errors
autocomplete	string	false	The HTML `autocomplete` attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholder	boolean	false	Will use the label provided as an accessible placeholder within the input
searchButton	object `<SearchButton>`	false	Settings for the search input button
postTextboxLinkText	string	false	The text for a link following the input
postTextboxLinkUrl	string	false	The URL for the HTML `href` attribute of the link following the textbox
listeners	object	false	Creates a `script` element that adds an event listener to the element by `id`. Takes `key { event }` and `value { function }`

InputPrefix/InputSuffix
Name	Type	Required	Description
text	string	true	The visible text abbreviation for the prefix or suffix, for example, “cm“
title	string	false	The 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)”.
id	string	true	The HTML `id` of the `<abbr>` element used for the prefix or suffix. Used for the input’s `aria-labelledby` attribute.

CharCheckLimit
Name	Type	Required	Description
id	string	true	The HTML `id` of the component
limit	integer	true	The maximum number of characters allowed in the input
charCountOverLimitPlural	string	true	The 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”.
charCountOverLimitSingular	string	true	The 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”.
charcheckCountdown	boolean	false	Set to “true” to show the character limit counter as characters are entered into the input
charCountPlural	string	true	The 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”.
charCountSingular	string	true	The 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
Name	Type	Required	Description
text	string	true	Text for the button label
type	string	false	Sets the HTML `type` attribute for the `<button>`. Can be set to either: “submit” or “reset”. Defaults to “button”.
id	string	false	Sets the HTML `id` attribute for the button
classes	string	false	Classes to add to the button component
iconType	string	false	Adds an icon to the button, before the label, by setting the icon type
attributes	object	false	HTML 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" />
</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

Nunjucksfor Example Input Text With Description
Nunjucks macro optionsfor Example Input Text With Description
HTMLfor Example Input Text With Description

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

Name	Type	Required	Description
id	string	true	The HTML `id` of the input. Used for the label’s `for` attribute.
type	string	false	Sets the HTML `type` attribute for the `<input>`. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classes	string	false	Classes to add to the input
width	string	false	Required width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
name	string	false	The HTML `name` attribute for the input
value	string or integer	false	The HTML `value` for the input to set a preset value for the field
min	integer	false	The HTML `min` attribute to set the minimum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
minLength	integer	false	The HTML `minlength` attribute to set the minimum accepted length of input value
maxLength	integer	false	The HTML `maxlength` attribute to set the maximum accepted length of input value
attributes	object	false	HTML attributes (for example, data attributes) to add to the input
label	`Label` (ref)	false	Settings for the input label. `for` will automatically be set to match the input id
prefix	object `<InputPrefix>`	false	Settings for the input prefix
suffix	object `<InputSuffix>`	false	Settings for the input suffix
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes to add to the field
dontWrap	boolean	false	Prevents the input from being wrapped in a field
mutuallyExclusive	`MutuallyExclusive` (ref)	false	Configuration object to set if the input has a mutually exclusive opposing option
charCheckLimit	object `<CharCheckLimit>`	false	Settings for a character counter or limit checker on the input
legend	string	false (unless `mutuallyExclusive` is set)	Text for the mutually exclusive fieldset‘s legend
legendClasses	string	false	Classes to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitle	boolean	true (unless `legend` is set)	Creates an `h1` inside the `legend`. Use when there is only a single fieldset on the page.
error	`Error` (ref)	false	Configuration for validation errors
autocomplete	string	false	The HTML `autocomplete` attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholder	boolean	false	Will use the label provided as an accessible placeholder within the input
searchButton	object `<SearchButton>`	false	Settings for the search input button
postTextboxLinkText	string	false	The text for a link following the input
postTextboxLinkUrl	string	false	The URL for the HTML `href` attribute of the link following the textbox
listeners	object	false	Creates a `script` element that adds an event listener to the element by `id`. Takes `key { event }` and `value { function }`

InputPrefix/InputSuffix
Name	Type	Required	Description
text	string	true	The visible text abbreviation for the prefix or suffix, for example, “cm“
title	string	false	The 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)”.
id	string	true	The HTML `id` of the `<abbr>` element used for the prefix or suffix. Used for the input’s `aria-labelledby` attribute.

CharCheckLimit
Name	Type	Required	Description
id	string	true	The HTML `id` of the component
limit	integer	true	The maximum number of characters allowed in the input
charCountOverLimitPlural	string	true	The 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”.
charCountOverLimitSingular	string	true	The 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”.
charcheckCountdown	boolean	false	Set to “true” to show the character limit counter as characters are entered into the input
charCountPlural	string	true	The 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”.
charCountSingular	string	true	The 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
Name	Type	Required	Description
text	string	true	Text for the button label
type	string	false	Sets the HTML `type` attribute for the `<button>`. Can be set to either: “submit” or “reset”. Defaults to “button”.
id	string	false	Sets the HTML `id` attribute for the button
classes	string	false	Classes to add to the button component
iconType	string	false	Adds an icon to the button, before the label, by setting the icon type
attributes	object	false	HTML attributes (for example, data attributes) to add to the button component

HTML

<div class="ons-field">
  <label class="ons-label ons-label--with-description" for="text-example-input-with-description"
    aria-describedby="description-hint">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

Nunjucksfor Example Input Text Width Constrained
Nunjucks macro optionsfor Example Input Text Width Constrained
HTMLfor Example Input Text Width Constrained

Nunjucks

{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "postcode",
        "width": "7",
        "autocomplete": "postal-code",
        "label": {
            "text": "Postcode"
        }
    })
}}

Nunjucks macro options

Name	Type	Required	Description
id	string	true	The HTML `id` of the input. Used for the label’s `for` attribute.
type	string	false	Sets the HTML `type` attribute for the `<input>`. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classes	string	false	Classes to add to the input
width	string	false	Required width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
name	string	false	The HTML `name` attribute for the input
value	string or integer	false	The HTML `value` for the input to set a preset value for the field
min	integer	false	The HTML `min` attribute to set the minimum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
minLength	integer	false	The HTML `minlength` attribute to set the minimum accepted length of input value
maxLength	integer	false	The HTML `maxlength` attribute to set the maximum accepted length of input value
attributes	object	false	HTML attributes (for example, data attributes) to add to the input
label	`Label` (ref)	false	Settings for the input label. `for` will automatically be set to match the input id
prefix	object `<InputPrefix>`	false	Settings for the input prefix
suffix	object `<InputSuffix>`	false	Settings for the input suffix
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes to add to the field
dontWrap	boolean	false	Prevents the input from being wrapped in a field
mutuallyExclusive	`MutuallyExclusive` (ref)	false	Configuration object to set if the input has a mutually exclusive opposing option
charCheckLimit	object `<CharCheckLimit>`	false	Settings for a character counter or limit checker on the input
legend	string	false (unless `mutuallyExclusive` is set)	Text for the mutually exclusive fieldset‘s legend
legendClasses	string	false	Classes to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitle	boolean	true (unless `legend` is set)	Creates an `h1` inside the `legend`. Use when there is only a single fieldset on the page.
error	`Error` (ref)	false	Configuration for validation errors
autocomplete	string	false	The HTML `autocomplete` attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholder	boolean	false	Will use the label provided as an accessible placeholder within the input
searchButton	object `<SearchButton>`	false	Settings for the search input button
postTextboxLinkText	string	false	The text for a link following the input
postTextboxLinkUrl	string	false	The URL for the HTML `href` attribute of the link following the textbox
listeners	object	false	Creates a `script` element that adds an event listener to the element by `id`. Takes `key { event }` and `value { function }`

InputPrefix/InputSuffix
Name	Type	Required	Description
text	string	true	The visible text abbreviation for the prefix or suffix, for example, “cm“
title	string	false	The 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)”.
id	string	true	The HTML `id` of the `<abbr>` element used for the prefix or suffix. Used for the input’s `aria-labelledby` attribute.

CharCheckLimit
Name	Type	Required	Description
id	string	true	The HTML `id` of the component
limit	integer	true	The maximum number of characters allowed in the input
charCountOverLimitPlural	string	true	The 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”.
charCountOverLimitSingular	string	true	The 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”.
charcheckCountdown	boolean	false	Set to “true” to show the character limit counter as characters are entered into the input
charCountPlural	string	true	The 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”.
charCountSingular	string	true	The 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
Name	Type	Required	Description
text	string	true	Text for the button label
type	string	false	Sets the HTML `type` attribute for the `<button>`. Can be set to either: “submit” or “reset”. Defaults to “button”.
id	string	false	Sets the HTML `id` attribute for the button
classes	string	false	Classes to add to the button component
iconType	string	false	Adds an icon to the button, before the label, by setting the icon type
attributes	object	false	HTML 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

Nunjucksfor Example Input Email
Nunjucks macro optionsfor Example Input Email
HTMLfor Example Input Email

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

Name	Type	Required	Description
id	string	true	The HTML `id` of the input. Used for the label’s `for` attribute.
type	string	false	Sets the HTML `type` attribute for the `<input>`. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classes	string	false	Classes to add to the input
width	string	false	Required width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
name	string	false	The HTML `name` attribute for the input
value	string or integer	false	The HTML `value` for the input to set a preset value for the field
min	integer	false	The HTML `min` attribute to set the minimum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
minLength	integer	false	The HTML `minlength` attribute to set the minimum accepted length of input value
maxLength	integer	false	The HTML `maxlength` attribute to set the maximum accepted length of input value
attributes	object	false	HTML attributes (for example, data attributes) to add to the input
label	`Label` (ref)	false	Settings for the input label. `for` will automatically be set to match the input id
prefix	object `<InputPrefix>`	false	Settings for the input prefix
suffix	object `<InputSuffix>`	false	Settings for the input suffix
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes to add to the field
dontWrap	boolean	false	Prevents the input from being wrapped in a field
mutuallyExclusive	`MutuallyExclusive` (ref)	false	Configuration object to set if the input has a mutually exclusive opposing option
charCheckLimit	object `<CharCheckLimit>`	false	Settings for a character counter or limit checker on the input
legend	string	false (unless `mutuallyExclusive` is set)	Text for the mutually exclusive fieldset‘s legend
legendClasses	string	false	Classes to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitle	boolean	true (unless `legend` is set)	Creates an `h1` inside the `legend`. Use when there is only a single fieldset on the page.
error	`Error` (ref)	false	Configuration for validation errors
autocomplete	string	false	The HTML `autocomplete` attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholder	boolean	false	Will use the label provided as an accessible placeholder within the input
searchButton	object `<SearchButton>`	false	Settings for the search input button
postTextboxLinkText	string	false	The text for a link following the input
postTextboxLinkUrl	string	false	The URL for the HTML `href` attribute of the link following the textbox
listeners	object	false	Creates a `script` element that adds an event listener to the element by `id`. Takes `key { event }` and `value { function }`

InputPrefix/InputSuffix
Name	Type	Required	Description
text	string	true	The visible text abbreviation for the prefix or suffix, for example, “cm“
title	string	false	The 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)”.
id	string	true	The HTML `id` of the `<abbr>` element used for the prefix or suffix. Used for the input’s `aria-labelledby` attribute.

CharCheckLimit
Name	Type	Required	Description
id	string	true	The HTML `id` of the component
limit	integer	true	The maximum number of characters allowed in the input
charCountOverLimitPlural	string	true	The 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”.
charCountOverLimitSingular	string	true	The 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”.
charcheckCountdown	boolean	false	Set to “true” to show the character limit counter as characters are entered into the input
charCountPlural	string	true	The 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”.
charCountSingular	string	true	The 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
Name	Type	Required	Description
text	string	true	Text for the button label
type	string	false	Sets the HTML `type` attribute for the `<button>`. Can be set to either: “submit” or “reset”. Defaults to “button”.
id	string	false	Sets the HTML `id` attribute for the button
classes	string	false	Classes to add to the button component
iconType	string	false	Adds an icon to the button, before the label, by setting the icon type
attributes	object	false	HTML attributes (for example, data attributes) to add to the button component

HTML

<div class="ons-field">
  <label class="ons-label ons-label--with-description" for="email-example-input-email"
    aria-describedby="description-hint">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

Nunjucksfor Example Input Telephone
Nunjucks macro optionsfor Example Input Telephone
HTMLfor Example Input Telephone

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

Name	Type	Required	Description
id	string	true	The HTML `id` of the input. Used for the label’s `for` attribute.
type	string	false	Sets the HTML `type` attribute for the `<input>`. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classes	string	false	Classes to add to the input
width	string	false	Required width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
name	string	false	The HTML `name` attribute for the input
value	string or integer	false	The HTML `value` for the input to set a preset value for the field
min	integer	false	The HTML `min` attribute to set the minimum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
minLength	integer	false	The HTML `minlength` attribute to set the minimum accepted length of input value
maxLength	integer	false	The HTML `maxlength` attribute to set the maximum accepted length of input value
attributes	object	false	HTML attributes (for example, data attributes) to add to the input
label	`Label` (ref)	false	Settings for the input label. `for` will automatically be set to match the input id
prefix	object `<InputPrefix>`	false	Settings for the input prefix
suffix	object `<InputSuffix>`	false	Settings for the input suffix
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes to add to the field
dontWrap	boolean	false	Prevents the input from being wrapped in a field
mutuallyExclusive	`MutuallyExclusive` (ref)	false	Configuration object to set if the input has a mutually exclusive opposing option
charCheckLimit	object `<CharCheckLimit>`	false	Settings for a character counter or limit checker on the input
legend	string	false (unless `mutuallyExclusive` is set)	Text for the mutually exclusive fieldset‘s legend
legendClasses	string	false	Classes to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitle	boolean	true (unless `legend` is set)	Creates an `h1` inside the `legend`. Use when there is only a single fieldset on the page.
error	`Error` (ref)	false	Configuration for validation errors
autocomplete	string	false	The HTML `autocomplete` attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholder	boolean	false	Will use the label provided as an accessible placeholder within the input
searchButton	object `<SearchButton>`	false	Settings for the search input button
postTextboxLinkText	string	false	The text for a link following the input
postTextboxLinkUrl	string	false	The URL for the HTML `href` attribute of the link following the textbox
listeners	object	false	Creates a `script` element that adds an event listener to the element by `id`. Takes `key { event }` and `value { function }`

InputPrefix/InputSuffix
Name	Type	Required	Description
text	string	true	The visible text abbreviation for the prefix or suffix, for example, “cm“
title	string	false	The 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)”.
id	string	true	The HTML `id` of the `<abbr>` element used for the prefix or suffix. Used for the input’s `aria-labelledby` attribute.

CharCheckLimit
Name	Type	Required	Description
id	string	true	The HTML `id` of the component
limit	integer	true	The maximum number of characters allowed in the input
charCountOverLimitPlural	string	true	The 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”.
charCountOverLimitSingular	string	true	The 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”.
charcheckCountdown	boolean	false	Set to “true” to show the character limit counter as characters are entered into the input
charCountPlural	string	true	The 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”.
charCountSingular	string	true	The 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
Name	Type	Required	Description
text	string	true	Text for the button label
type	string	false	Sets the HTML `type` attribute for the `<button>`. Can be set to either: “submit” or “reset”. Defaults to “button”.
id	string	false	Sets the HTML `id` attribute for the button
classes	string	false	Classes to add to the button component
iconType	string	false	Adds an icon to the button, before the label, by setting the icon type
attributes	object	false	HTML attributes (for example, data attributes) to add to the button component

HTML

<div class="ons-field">
  <label class="ons-label ons-label--with-description" for="telephone" aria-describedby="description-hint">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

Nunjucksfor Example Input Number Prefixed
Nunjucks macro optionsfor Example Input Number Prefixed
HTMLfor Example Input Number Prefixed

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

Name	Type	Required	Description
id	string	true	The HTML `id` of the input. Used for the label’s `for` attribute.
type	string	false	Sets the HTML `type` attribute for the `<input>`. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classes	string	false	Classes to add to the input
width	string	false	Required width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
name	string	false	The HTML `name` attribute for the input
value	string or integer	false	The HTML `value` for the input to set a preset value for the field
min	integer	false	The HTML `min` attribute to set the minimum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
minLength	integer	false	The HTML `minlength` attribute to set the minimum accepted length of input value
maxLength	integer	false	The HTML `maxlength` attribute to set the maximum accepted length of input value
attributes	object	false	HTML attributes (for example, data attributes) to add to the input
label	`Label` (ref)	false	Settings for the input label. `for` will automatically be set to match the input id
prefix	object `<InputPrefix>`	false	Settings for the input prefix
suffix	object `<InputSuffix>`	false	Settings for the input suffix
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes to add to the field
dontWrap	boolean	false	Prevents the input from being wrapped in a field
mutuallyExclusive	`MutuallyExclusive` (ref)	false	Configuration object to set if the input has a mutually exclusive opposing option
charCheckLimit	object `<CharCheckLimit>`	false	Settings for a character counter or limit checker on the input
legend	string	false (unless `mutuallyExclusive` is set)	Text for the mutually exclusive fieldset‘s legend
legendClasses	string	false	Classes to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitle	boolean	true (unless `legend` is set)	Creates an `h1` inside the `legend`. Use when there is only a single fieldset on the page.
error	`Error` (ref)	false	Configuration for validation errors
autocomplete	string	false	The HTML `autocomplete` attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholder	boolean	false	Will use the label provided as an accessible placeholder within the input
searchButton	object `<SearchButton>`	false	Settings for the search input button
postTextboxLinkText	string	false	The text for a link following the input
postTextboxLinkUrl	string	false	The URL for the HTML `href` attribute of the link following the textbox
listeners	object	false	Creates a `script` element that adds an event listener to the element by `id`. Takes `key { event }` and `value { function }`

InputPrefix/InputSuffix
Name	Type	Required	Description
text	string	true	The visible text abbreviation for the prefix or suffix, for example, “cm“
title	string	false	The 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)”.
id	string	true	The HTML `id` of the `<abbr>` element used for the prefix or suffix. Used for the input’s `aria-labelledby` attribute.

CharCheckLimit
Name	Type	Required	Description
id	string	true	The HTML `id` of the component
limit	integer	true	The maximum number of characters allowed in the input
charCountOverLimitPlural	string	true	The 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”.
charCountOverLimitSingular	string	true	The 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”.
charcheckCountdown	boolean	false	Set to “true” to show the character limit counter as characters are entered into the input
charCountPlural	string	true	The 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”.
charCountSingular	string	true	The 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
Name	Type	Required	Description
text	string	true	Text for the button label
type	string	false	Sets the HTML `type` attribute for the `<button>`. Can be set to either: “submit” or “reset”. Defaults to “button”.
id	string	false	Sets the HTML `id` attribute for the button
classes	string	false	Classes to add to the button component
iconType	string	false	Adds an icon to the button, before the label, by setting the icon type
attributes	object	false	HTML 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.

Open this example in a new tab(Example Input Text With Character Limit Checker)

Example Input Text With Character Limit Checker contents

Nunjucksfor Example Input Text With Character Limit Checker
Nunjucks macro optionsfor Example Input Text With Character Limit Checker
HTMLfor Example Input Text With Character Limit Checker

Nunjucks

{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "text-example-input-with-char-limit-checker",
        "label": {
            "text": "Enter some text"
        },
        "width": "10",
        "charCheckLimit": {
            "limit": 10,
            "charCountOverLimitSingular": "{x} character too many",
            "charCountOverLimitPlural": "{x} characters too many",
            "charCountSingular": "You have {x} character remaining",
            "charCountPlural": "You have {x} characters remaining"
        }
    })
}}

Nunjucks macro options

Name	Type	Required	Description
id	string	true	The HTML `id` of the input. Used for the label’s `for` attribute.
type	string	false	Sets the HTML `type` attribute for the `<input>`. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classes	string	false	Classes to add to the input
width	string	false	Required width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
name	string	false	The HTML `name` attribute for the input
value	string or integer	false	The HTML `value` for the input to set a preset value for the field
min	integer	false	The HTML `min` attribute to set the minimum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
minLength	integer	false	The HTML `minlength` attribute to set the minimum accepted length of input value
maxLength	integer	false	The HTML `maxlength` attribute to set the maximum accepted length of input value
attributes	object	false	HTML attributes (for example, data attributes) to add to the input
label	`Label` (ref)	false	Settings for the input label. `for` will automatically be set to match the input id
prefix	object `<InputPrefix>`	false	Settings for the input prefix
suffix	object `<InputSuffix>`	false	Settings for the input suffix
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes to add to the field
dontWrap	boolean	false	Prevents the input from being wrapped in a field
mutuallyExclusive	`MutuallyExclusive` (ref)	false	Configuration object to set if the input has a mutually exclusive opposing option
charCheckLimit	object `<CharCheckLimit>`	false	Settings for a character counter or limit checker on the input
legend	string	false (unless `mutuallyExclusive` is set)	Text for the mutually exclusive fieldset‘s legend
legendClasses	string	false	Classes to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitle	boolean	true (unless `legend` is set)	Creates an `h1` inside the `legend`. Use when there is only a single fieldset on the page.
error	`Error` (ref)	false	Configuration for validation errors
autocomplete	string	false	The HTML `autocomplete` attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholder	boolean	false	Will use the label provided as an accessible placeholder within the input
searchButton	object `<SearchButton>`	false	Settings for the search input button
postTextboxLinkText	string	false	The text for a link following the input
postTextboxLinkUrl	string	false	The URL for the HTML `href` attribute of the link following the textbox
listeners	object	false	Creates a `script` element that adds an event listener to the element by `id`. Takes `key { event }` and `value { function }`

InputPrefix/InputSuffix
Name	Type	Required	Description
text	string	true	The visible text abbreviation for the prefix or suffix, for example, “cm“
title	string	false	The 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)”.
id	string	true	The HTML `id` of the `<abbr>` element used for the prefix or suffix. Used for the input’s `aria-labelledby` attribute.

CharCheckLimit
Name	Type	Required	Description
id	string	true	The HTML `id` of the component
limit	integer	true	The maximum number of characters allowed in the input
charCountOverLimitPlural	string	true	The 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”.
charCountOverLimitSingular	string	true	The 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”.
charcheckCountdown	boolean	false	Set to “true” to show the character limit counter as characters are entered into the input
charCountPlural	string	true	The 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”.
charCountSingular	string	true	The 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
Name	Type	Required	Description
text	string	true	Text for the button label
type	string	false	Sets the HTML `type` attribute for the `<button>`. Can be set to either: “submit” or “reset”. Defaults to “button”.
id	string	false	Sets the HTML `id` attribute for the button
classes	string	false	Classes to add to the button component
iconType	string	false	Adds an icon to the button, before the label, by setting the icon type
attributes	object	false	HTML 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" for="text-example-input-with-char-limit-checker">Enter some text</label>
    <input type="text" id="text-example-input-with-char-limit-checker"
      class="ons-input ons-input--text ons-input-type__input ons-input--w-10"
      data-char-check-ref="text-example-input-with-char-limit-checker-check" data-char-check-num="10"
      aria-describedby="text-example-input-with-char-limit-checker-check" />
  </span>
  <span id="text-example-input-with-char-limit-checker-check"
    class="ons-input__limit ons-u-fs-s--b ons-u-d-no ons-u-mt-2xs"
    data-charcount-singular="You have {x} character remaining" data-charcount-plural="You have {x} characters remaining"
    data-charcount-limit-singular="{x} character too many" data-charcount-limit-plural="{x} characters too many">
  </span>
</div>

Search

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

Example Input Search contents

Nunjucksfor Example Input Search
Nunjucks macro optionsfor Example Input Search
HTMLfor Example Input Search

Nunjucks

{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": 'search-field',
        "label": {
            'text': 'Search',
            "classes": 'ons-u-pb-3xs ons-u-mb-no'
        },
        "searchButton": {
            "visuallyHideButtonText": true,
            "text": 'Search',
            "iconType": 'search'
        }
    })
}}

Nunjucks macro options

Name	Type	Required	Description
id	string	true	The HTML `id` of the input. Used for the label’s `for` attribute.
type	string	false	Sets the HTML `type` attribute for the `<input>`. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classes	string	false	Classes to add to the input
width	string	false	Required width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
name	string	false	The HTML `name` attribute for the input
value	string or integer	false	The HTML `value` for the input to set a preset value for the field
min	integer	false	The HTML `min` attribute to set the minimum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
minLength	integer	false	The HTML `minlength` attribute to set the minimum accepted length of input value
maxLength	integer	false	The HTML `maxlength` attribute to set the maximum accepted length of input value
attributes	object	false	HTML attributes (for example, data attributes) to add to the input
label	`Label` (ref)	false	Settings for the input label. `for` will automatically be set to match the input id
prefix	object `<InputPrefix>`	false	Settings for the input prefix
suffix	object `<InputSuffix>`	false	Settings for the input suffix
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes to add to the field
dontWrap	boolean	false	Prevents the input from being wrapped in a field
mutuallyExclusive	`MutuallyExclusive` (ref)	false	Configuration object to set if the input has a mutually exclusive opposing option
charCheckLimit	object `<CharCheckLimit>`	false	Settings for a character counter or limit checker on the input
legend	string	false (unless `mutuallyExclusive` is set)	Text for the mutually exclusive fieldset‘s legend
legendClasses	string	false	Classes to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitle	boolean	true (unless `legend` is set)	Creates an `h1` inside the `legend`. Use when there is only a single fieldset on the page.
error	`Error` (ref)	false	Configuration for validation errors
autocomplete	string	false	The HTML `autocomplete` attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholder	boolean	false	Will use the label provided as an accessible placeholder within the input
searchButton	object `<SearchButton>`	false	Settings for the search input button
postTextboxLinkText	string	false	The text for a link following the input
postTextboxLinkUrl	string	false	The URL for the HTML `href` attribute of the link following the textbox
listeners	object	false	Creates a `script` element that adds an event listener to the element by `id`. Takes `key { event }` and `value { function }`

InputPrefix/InputSuffix
Name	Type	Required	Description
text	string	true	The visible text abbreviation for the prefix or suffix, for example, “cm“
title	string	false	The 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)”.
id	string	true	The HTML `id` of the `<abbr>` element used for the prefix or suffix. Used for the input’s `aria-labelledby` attribute.

CharCheckLimit
Name	Type	Required	Description
id	string	true	The HTML `id` of the component
limit	integer	true	The maximum number of characters allowed in the input
charCountOverLimitPlural	string	true	The 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”.
charCountOverLimitSingular	string	true	The 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”.
charcheckCountdown	boolean	false	Set to “true” to show the character limit counter as characters are entered into the input
charCountPlural	string	true	The 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”.
charCountSingular	string	true	The 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
Name	Type	Required	Description
text	string	true	Text for the button label
type	string	false	Sets the HTML `type` attribute for the `<button>`. Can be set to either: “submit” or “reset”. Defaults to “button”.
id	string	false	Sets the HTML `id` attribute for the button
classes	string	false	Classes to add to the button component
iconType	string	false	Adds an icon to the button, before the label, by setting the icon type
attributes	object	false	HTML attributes (for example, data attributes) to add to the button component

HTML

<div class="ons-field">
  <label class="ons-label ons-u-pb-3xs ons-u-mb-no" for="search-field">Search</label>
  <span class="ons-grid-flex ons-grid-flex--vertical-top ons-input_search-button">
    <input type="search" id="search-field" class="ons-input ons-input--text ons-input-type__input ons-search__input" />
    <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" role="img" title="ons-icon-search">
          <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@2xs@s"><span class="ons-u-vh">Search</span></span></span>
    </button>
  </span>
</div>

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

Example Input Search With Placeholder contents

Nunjucksfor Example Input Search With Placeholder
Nunjucks macro optionsfor Example Input Search With Placeholder
HTMLfor Example Input Search With Placeholder

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

Name	Type	Required	Description
id	string	true	The HTML `id` of the input. Used for the label’s `for` attribute.
type	string	false	Sets the HTML `type` attribute for the `<input>`. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classes	string	false	Classes to add to the input
width	string	false	Required width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
name	string	false	The HTML `name` attribute for the input
value	string or integer	false	The HTML `value` for the input to set a preset value for the field
min	integer	false	The HTML `min` attribute to set the minimum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
minLength	integer	false	The HTML `minlength` attribute to set the minimum accepted length of input value
maxLength	integer	false	The HTML `maxlength` attribute to set the maximum accepted length of input value
attributes	object	false	HTML attributes (for example, data attributes) to add to the input
label	`Label` (ref)	false	Settings for the input label. `for` will automatically be set to match the input id
prefix	object `<InputPrefix>`	false	Settings for the input prefix
suffix	object `<InputSuffix>`	false	Settings for the input suffix
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes to add to the field
dontWrap	boolean	false	Prevents the input from being wrapped in a field
mutuallyExclusive	`MutuallyExclusive` (ref)	false	Configuration object to set if the input has a mutually exclusive opposing option
charCheckLimit	object `<CharCheckLimit>`	false	Settings for a character counter or limit checker on the input
legend	string	false (unless `mutuallyExclusive` is set)	Text for the mutually exclusive fieldset‘s legend
legendClasses	string	false	Classes to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitle	boolean	true (unless `legend` is set)	Creates an `h1` inside the `legend`. Use when there is only a single fieldset on the page.
error	`Error` (ref)	false	Configuration for validation errors
autocomplete	string	false	The HTML `autocomplete` attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholder	boolean	false	Will use the label provided as an accessible placeholder within the input
searchButton	object `<SearchButton>`	false	Settings for the search input button
postTextboxLinkText	string	false	The text for a link following the input
postTextboxLinkUrl	string	false	The URL for the HTML `href` attribute of the link following the textbox
listeners	object	false	Creates a `script` element that adds an event listener to the element by `id`. Takes `key { event }` and `value { function }`

InputPrefix/InputSuffix
Name	Type	Required	Description
text	string	true	The visible text abbreviation for the prefix or suffix, for example, “cm“
title	string	false	The 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)”.
id	string	true	The HTML `id` of the `<abbr>` element used for the prefix or suffix. Used for the input’s `aria-labelledby` attribute.

CharCheckLimit
Name	Type	Required	Description
id	string	true	The HTML `id` of the component
limit	integer	true	The maximum number of characters allowed in the input
charCountOverLimitPlural	string	true	The 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”.
charCountOverLimitSingular	string	true	The 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”.
charcheckCountdown	boolean	false	Set to “true” to show the character limit counter as characters are entered into the input
charCountPlural	string	true	The 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”.
charCountSingular	string	true	The 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
Name	Type	Required	Description
text	string	true	Text for the button label
type	string	false	Sets the HTML `type` attribute for the `<button>`. Can be set to either: “submit” or “reset”. Defaults to “button”.
id	string	false	Sets the HTML `id` attribute for the button
classes	string	false	Classes to add to the button component
iconType	string	false	Adds an icon to the button, before the label, by setting the icon type
attributes	object	false	HTML attributes (for example, data attributes) to add to the button component

HTML

<div class="ons-field">
  <span class="ons-grid-flex ons-grid-flex--vertical-top 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" role="img" title="ons-icon-search">
          <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@2xs@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.

Open this example in a new tab(Example Input Search With Character Check)

Example Input Search With Character Check contents

Nunjucksfor Example Input Search With Character Check
Nunjucks macro optionsfor Example Input Search With Character Check
HTMLfor Example Input Search With Character Check

Nunjucks

{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": 'search-field',
        "label": {
            'text': 'Filter results',
            "classes": 'ons-u-pb-3xs 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

Name	Type	Required	Description
id	string	true	The HTML `id` of the input. Used for the label’s `for` attribute.
type	string	false	Sets the HTML `type` attribute for the `<input>`. Can be set to either: “number”, “email”, “tel”, “password”, or “search”. Defaults to “text”.
classes	string	false	Classes to add to the input
width	string	false	Required width of the input in number of letters or digits. Will also accept a breakpoint suffix, for example, “7@m”.
name	string	false	The HTML `name` attribute for the input
value	string or integer	false	The HTML `value` for the input to set a preset value for the field
min	integer	false	The HTML `min` attribute to set the minimum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input (only to be used when type is set to one of date, month, week, time, datetime-local or range)
minLength	integer	false	The HTML `minlength` attribute to set the minimum accepted length of input value
maxLength	integer	false	The HTML `maxlength` attribute to set the maximum accepted length of input value
attributes	object	false	HTML attributes (for example, data attributes) to add to the input
label	`Label` (ref)	false	Settings for the input label. `for` will automatically be set to match the input id
prefix	object `<InputPrefix>`	false	Settings for the input prefix
suffix	object `<InputSuffix>`	false	Settings for the input suffix
fieldId	string	false	The HTML `id` of the field
fieldClasses	string	false	Classes to add to the field
dontWrap	boolean	false	Prevents the input from being wrapped in a field
mutuallyExclusive	`MutuallyExclusive` (ref)	false	Configuration object to set if the input has a mutually exclusive opposing option
charCheckLimit	object `<CharCheckLimit>`	false	Settings for a character counter or limit checker on the input
legend	string	false (unless `mutuallyExclusive` is set)	Text for the mutually exclusive fieldset‘s legend
legendClasses	string	false	Classes to add to the mutually exclusive fieldset‘s legend
legendIsQuestionTitle	boolean	true (unless `legend` is set)	Creates an `h1` inside the `legend`. Use when there is only a single fieldset on the page.
error	`Error` (ref)	false	Configuration for validation errors
autocomplete	string	false	The HTML `autocomplete` attribute used to specify the purpose of the input or prevent the browser’s native autofill
accessiblePlaceholder	boolean	false	Will use the label provided as an accessible placeholder within the input
searchButton	object `<SearchButton>`	false	Settings for the search input button
postTextboxLinkText	string	false	The text for a link following the input
postTextboxLinkUrl	string	false	The URL for the HTML `href` attribute of the link following the textbox
listeners	object	false	Creates a `script` element that adds an event listener to the element by `id`. Takes `key { event }` and `value { function }`

InputPrefix/InputSuffix
Name	Type	Required	Description
text	string	true	The visible text abbreviation for the prefix or suffix, for example, “cm“
title	string	false	The 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)”.
id	string	true	The HTML `id` of the `<abbr>` element used for the prefix or suffix. Used for the input’s `aria-labelledby` attribute.

CharCheckLimit
Name	Type	Required	Description
id	string	true	The HTML `id` of the component
limit	integer	true	The maximum number of characters allowed in the input
charCountOverLimitPlural	string	true	The 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”.
charCountOverLimitSingular	string	true	The 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”.
charcheckCountdown	boolean	false	Set to “true” to show the character limit counter as characters are entered into the input
charCountPlural	string	true	The 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”.
charCountSingular	string	true	The 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
Name	Type	Required	Description
text	string	true	Text for the button label
type	string	false	Sets the HTML `type` attribute for the `<button>`. Can be set to either: “submit” or “reset”. Defaults to “button”.
id	string	false	Sets the HTML `id` attribute for the button
classes	string	false	Classes to add to the button component
iconType	string	false	Adds an icon to the button, before the label, by setting the icon type
attributes	object	false	HTML 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-3xs ons-u-mb-no" for="search-field">Filter results</label>
    <span class="ons-grid-flex ons-grid-flex--vertical-top 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-2xs"
    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

Nunjucksfor Example Input Email With Error
HTMLfor Example Input Email With Error

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" for="email-example-input-email-with-error"
        aria-describedby="description-hint">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)

Cookies on ons.gov.uk

Input

Overview

Example Input Text contents

Nunjucks

Nunjucks macro options

HTML

When to use this component

When not to use this component

How to use this component

Autocomplete

Width constrained

Example Input Number contents

Nunjucks

Nunjucks macro options

HTML

Variants

Input with description

Example Input Text With Description contents

Nunjucks

Nunjucks macro options

HTML

Addresses

Postcodes

Example Input Text Width Constrained contents

Nunjucks

Nunjucks macro options

HTML

Email

Example Input Email contents

Nunjucks

Nunjucks macro options

HTML

Telephone

Example Input Telephone contents

Nunjucks

Nunjucks macro options

HTML

Number

Example Input Number Prefixed contents

Nunjucks

Nunjucks macro options

HTML

Character limit checker

Example Input Text With Character Limit Checker contents

Nunjucks

Nunjucks macro options

HTML

Search

Example Input Search contents

Nunjucks

Nunjucks macro options

HTML

Example Input Search With Placeholder contents

Nunjucks

Nunjucks macro options

HTML

Example Input Search With Character Check contents

Nunjucks

Nunjucks macro options

HTML

How to check an input field

Error messages

Example Input Email With Error contents

Nunjucks

HTML

Empty input fields

Invalid formatting

Research on this component

Help improve this page