Ask users for Email addresses

Overview

Use the email addresses pattern to ask a user for an email address.

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
max	integer	false	The HTML `max` attribute to set the maximum accepted number or date for the input
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>

When to use this pattern

Use this pattern when you need to collect an email address from the user.

How to use this pattern

When using this pattern you should:

tell users why you need an email address and what it will be used for
make sure the field can accept all email addresses
help users enter an email address in the correct format

Explain why you need the email address

Use the ons-label__description with the input component to reassure users why you need an email address and what it will be used for.

Allow all email addresses

The email address field needs to accommodate the maximum number of characters allowed. An email address can be up to 320 characters long and include a set of special characters as detailed in the RFC 3696 specification from the Internet Engineering Task Force (opens in a new tab)

How to check email addresses

To help users enter a valid email address, you should:

allow them to paste the email address
check they have entered something in the email address 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
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 email address field.

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>

If the email address field is empty

Use “Enter an email address”.

If the email address entered is not in a valid format

Use “Enter an email address in a valid format, for example, name@example.com”.

Help improve this page

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

Cookies on ons.gov.uk

Ask users for Email addresses

Overview

Example Input Email contents

Nunjucks

Nunjucks macro options

HTML

When to use this pattern

How to use this pattern

Explain why you need the email address

Allow all email addresses

How to check email addresses

Error messages

Example Input Email With Error contents

Nunjucks

HTML

If the email address field is empty

If the email address entered is not in a valid format

Help improve this page