Ask users for Phone numbers

Overview

How to ask users for a phone number.

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>

When to use this pattern

Only ask users for a phone number when your service has a genuine need for this information. For example, to send an access code by text message.

How to use this pattern

This pattern uses the input component.

Set the input type to tel to bring up the correct keypad on touch devices.

When using this pattern you should:

make it clear what type of telephone number you need
tell users why you need a phone number and what it will be used for
let users know if you will contact them and when
make sure you allow the user to enter a phone number in a familiar format
help users enter a phone number in the correct format

Make it clear what type of phone number you need

Use the input label with the input component to let users know what type of phone number you need, for example, a UK, international or mobile phone number.

Explain why you need the phone number

Use the optional ons-label__description for hint text to reassure users why you need a phone number and what it will be used for.

Allow all phone number formats

The phone number field must accommodate all phone number variations so the user can enter a number in the format they are used to. The length of the field can be adjusted using the input width classes to allow for any spaces or common characters, for example, brackets, dashes or country codes.

Validate phone numbers

To help users enter a valid phone number, you should:

check they have entered the phone number correctly
show error validation messages if they have not entered a valid phone number
allow them to paste the phone number
ask them to confirm it is correct using the check answers pattern

Error messages

Use the correct errors pattern and show the error details above the phone number field if it is missing or incorrect.

Nunjucks

{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "tel-example-phone-number-error",
        "width": "15",
        "type": "tel",
        "autocomplete": "tel",
        "value": "not a number",
        "label": {
            "text": "UK mobile number",
            "description": "This will not be stored and only used once to send the access code"
        },
        "error": {
            "id": "email-error-example-phone-number-error",
            "text": "Enter a UK mobile number in a valid format, for example, 07700 912345 or +44 7700 912345"
        }
    })
}}

HTML

<div class="ons-panel ons-panel--error ons-panel--no-title" id="email-error-example-phone-number-error">
  <span class="ons-panel__assistive-text ons-u-vh">Error: </span>
  <div class="ons-panel__body">
    <p class="ons-panel__error">
      <strong>Enter a UK mobile number in a valid format, for example, 07700 912345 or +44 7700 912345</strong>
    </p>
    <div class="ons-field">
      <label class="ons-label ons-label--with-description" for="tel-example-phone-number-error"
        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 the access code</span>
      <input type="tel" id="tel-example-phone-number-error"
        class="ons-input ons-input--text ons-input-type__input ons-input--error ons-input-number--w-15"
        value="not a number" autocomplete="tel" aria-describedby="description-hint" />
    </div>
  </div>
</div>

If the phone number is missing

Use “Enter [the required type of phone number]”, for example, “Enter a UK mobile number”.

If a phone number is incorrect

Use “Enter a UK mobile number in a valid format, for example, 07700 912345 or +44 7700 912345”, to give them a clear example of a valid phone number.

Make sure any examples of phone numbers in the error message are suitable for the type of number you are asking for. Ofcom maintains a list of numbers (opens in a new tab) reserved for use in media that you can use.

Use autocomplete

Use the autocomplete attribute when you are asking for a phone number as it helps the user fill out a form more quickly.

To do this, set the autocomplete attribute on the input field to tel.

You will need to use the autocomplete attribute to meet WCAG 2.1 AA standards for accessibility (opens in a new tab)

Help improve this page

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

Cookies on ons.gov.uk

Ask users for Phone numbers

Overview

Example Input Telephone contents

Nunjucks

Nunjucks macro options

HTML

When to use this pattern

How to use this pattern

Make it clear what type of phone number you need

Explain why you need the phone number

Allow all phone number formats

Validate phone numbers

Error messages

Example Phone Number Error contents

Nunjucks

HTML

If the phone number is missing

If a phone number is incorrect

Use autocomplete

Help improve this page