Follow the validation pattern and show an error message when there is a validation error. In the error message explain what went wrong and how to fix it.
<fieldsetclass="govuk-fieldset"role="group"aria-describedby="passport-issued-hint passport-issued-error"><legendclass="govuk-fieldset__legend govuk-fieldset__legend--l"><h1class="govuk-fieldset__heading">
When was your passport issued?
</h1></legend><divid="passport-issued-hint"class="govuk-hint">
For example, 27 3 2007
</div><pid="passport-issued-error"class="govuk-error-message"><spanclass="govuk-visually-hidden">Error:</span> The date your passport was issued must be in the past
</p><divclass="govuk-date-input"id="passport-issued"><divclass="govuk-date-input__item"><divclass="govuk-form-group"><labelclass="govuk-label govuk-date-input__label"for="passport-issued-day">
Day
</label><inputclass="govuk-input govuk-date-input__input govuk-input--width-2 govuk-input--error"id="passport-issued-day"name="passport-issued-day"type="text"value="6"inputmode="numeric"></div></div><divclass="govuk-date-input__item"><divclass="govuk-form-group"><labelclass="govuk-label govuk-date-input__label"for="passport-issued-month">
Month
</label><inputclass="govuk-input govuk-date-input__input govuk-input--width-2 govuk-input--error"id="passport-issued-month"name="passport-issued-month"type="text"value="3"inputmode="numeric"></div></div><divclass="govuk-date-input__item"><divclass="govuk-form-group"><labelclass="govuk-label govuk-date-input__label"for="passport-issued-year">
Year
</label><inputclass="govuk-input govuk-date-input__input govuk-input--width-4 govuk-input--error"id="passport-issued-year"name="passport-issued-year"type="text"value="2076"inputmode="numeric"></div></div></div></fieldset></div>
<p>
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
</p>
<p>
Some options are required for the macro to work; these are marked as "Required" in the option description.
</p>
<p>
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
</p>
<table class="govuk-table app-options__table" id="options-error-message-example--primary">
<caption class="govuk-table__caption govuk-heading-m govuk-visually-hidden">Primary options</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>html</code> is set, this is not required. Text to use within the error message. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>text</code> is set, this is not required. HTML to use within the error message. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">id</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
ID attribute to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">classes</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Classes to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">attributes</th>
<td class="govuk-table__cell ">object</td>
<td class="govuk-table__cell ">
HTML attributes (for example data attributes) to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">visuallyHiddenText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
A visually hidden prefix used before the error message. Defaults to 'Error'.
</td>
</tr>
</tbody>
</table>
{{ govukDateInput({
fieldset: {
legend: {
text: "When was your passport issued?",
isPageHeading: true,
classes: "govuk-fieldset__legend--l"
}
},
hint: {
text: "For example, 27 3 2007"
},
errorMessage: {
text: "The date your passport was issued must be in the past"
},
id: "passport-issued",
namePrefix: "passport-issued",
items: [
{
classes: "govuk-input--width-2 govuk-input--error",
name: "day",
value: "6"
},
{
classes: "govuk-input--width-2 govuk-input--error",
name: "month",
value: "3"
},
{
classes: "govuk-input--width-4 govuk-input--error",
name: "year",
value: "2076"
}
]
}) }}
When to use this component
Show an error message next to the field and in the error summary when there is a validation error.
Use standard messages for different components.
When not to use this component
Do not use error messages to tell a user that they are not eligible or do not have permission to do something. Or to tell them about a lack of capacity or other problem the user cannot fix - because the problem is with the service rather than with the information the user has provided.
Instead, take the user to a page that explains the problem (for example, telling them why they’re not eligible) and provides useful information about what to do next.
put the message in red after the question text and hint text
use a red border to visually connect the message and the question it belongs to
if the error relates to a specific field within the question, give it a red border and refer to that field in the error message - for example: "you must enter a year"
To help screen reader users, the error message component includes a hidden 'Error:' before the error message. These users will hear, for example, "Error: The date your passport was issued must be in the past".
If your error message is written in another language, you can change the prefix as needed, as shown in this example.
<p>
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
</p>
<p>
Some options are required for the macro to work; these are marked as "Required" in the option description.
</p>
<p>
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
</p>
<table class="govuk-table app-options__table" id="options-error-message-with-a-custom-visually-hidden-prefix-example-open--primary">
<caption class="govuk-table__caption govuk-heading-m govuk-visually-hidden">Primary options</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>html</code> is set, this is not required. Text to use within the error message. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>text</code> is set, this is not required. HTML to use within the error message. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">id</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
ID attribute to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">classes</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Classes to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">attributes</th>
<td class="govuk-table__cell ">object</td>
<td class="govuk-table__cell ">
HTML attributes (for example data attributes) to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">visuallyHiddenText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
A visually hidden prefix used before the error message. Defaults to 'Error'.
</td>
</tr>
</tbody>
</table>
Summarise all errors at the top of the page the user is on using an error summary.
There are 2 ways to use the error message component. You can use HTML or, if you are using Nunjucks or the GOV.UK Prototype Kit, you can use the Nunjucks macro.
<fieldsetclass="govuk-fieldset"aria-describedby="nationality-hint nationality-error"><legendclass="govuk-fieldset__legend govuk-fieldset__legend--l"><h1class="govuk-fieldset__heading">
What is your nationality?
</h1></legend><divid="nationality-hint"class="govuk-hint">
If you have dual nationality, select all options that are relevant to you.
</div><pid="nationality-error"class="govuk-error-message"><spanclass="govuk-visually-hidden">Error:</span> Select if you are British, Irish or a citizen of a different country
</p><divclass="govuk-checkboxes"data-module="govuk-checkboxes"><divclass="govuk-checkboxes__item"><inputclass="govuk-checkboxes__input"id="nationality"name="nationality"type="checkbox"value="british"><labelclass="govuk-label govuk-checkboxes__label"for="nationality">
British
</label></div><divclass="govuk-checkboxes__item"><inputclass="govuk-checkboxes__input"id="nationality-2"name="nationality"type="checkbox"value="irish"><labelclass="govuk-label govuk-checkboxes__label"for="nationality-2">
Irish
</label></div><divclass="govuk-checkboxes__item"><inputclass="govuk-checkboxes__input"id="nationality-3"name="nationality"type="checkbox"value="other"><labelclass="govuk-label govuk-checkboxes__label"for="nationality-3">
Citizen of another country
</label></div></div></fieldset></div>
<p>
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
</p>
<p>
Some options are required for the macro to work; these are marked as "Required" in the option description.
</p>
<p>
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
</p>
<table class="govuk-table app-options__table" id="options-error-message-with-legend-example--primary">
<caption class="govuk-table__caption govuk-heading-m govuk-visually-hidden">Primary options</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>html</code> is set, this is not required. Text to use within the error message. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>text</code> is set, this is not required. HTML to use within the error message. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">id</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
ID attribute to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">classes</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Classes to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">attributes</th>
<td class="govuk-table__cell ">object</td>
<td class="govuk-table__cell ">
HTML attributes (for example data attributes) to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">visuallyHiddenText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
A visually hidden prefix used before the error message. Defaults to 'Error'.
</td>
</tr>
</tbody>
</table>
{{ govukCheckboxes({
name: "nationality",
fieldset: {
legend: {
text: "What is your nationality?",
isPageHeading: true,
classes: "govuk-fieldset__legend--l"
}
},
hint: {
text: "If you have dual nationality, select all options that are relevant to you."
},
errorMessage: {
text: "Select if you are British, Irish or a citizen of a different country"
},
items: [
{
value: "british",
text: "British"
},
{
value: "irish",
text: "Irish"
},
{
value: "other",
text: "Citizen of another country"
}
]
}) }}
<labelclass="govuk-label"for="national-insurance-number">
National Insurance number
</label><divid="national-insurance-number-hint"class="govuk-hint">
It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’.
</div><pid="national-insurance-number-error"class="govuk-error-message"><spanclass="govuk-visually-hidden">Error:</span> Enter a National Insurance number in the correct format
</p><inputclass="govuk-input govuk-input--error"id="national-insurance-number"name="national-insurance-number"type="text"aria-describedby="national-insurance-number-hint national-insurance-number-error"></div>
<p>
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
</p>
<p>
Some options are required for the macro to work; these are marked as "Required" in the option description.
</p>
<p>
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
</p>
<table class="govuk-table app-options__table" id="options-error-message-with-label-example--primary">
<caption class="govuk-table__caption govuk-heading-m govuk-visually-hidden">Primary options</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>html</code> is set, this is not required. Text to use within the error message. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>text</code> is set, this is not required. HTML to use within the error message. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">id</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
ID attribute to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">classes</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Classes to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">attributes</th>
<td class="govuk-table__cell ">object</td>
<td class="govuk-table__cell ">
HTML attributes (for example data attributes) to add to the error message span tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">visuallyHiddenText</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
A visually hidden prefix used before the error message. Defaults to 'Error'.
</td>
</tr>
</tbody>
</table>
{{ govukInput({
label: {
text: "National Insurance number"
},
hint: {
text: "It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’."
},
id: "national-insurance-number",
name: "national-insurance-number",
errorMessage: {
text: "Enter a National Insurance number in the correct format"
}
}) }}
Be clear and concise
Describe what has happened and tell them how to fix it. The message must be in plain English, use positive language and get to the point.
Do not use:
technical jargon like ‘form post error’, ‘unspecified error’ and ‘error 0x0000000643’
words like ‘forbidden’, ‘illegal’, ‘you forgot’ and ‘prohibited’
‘please’ because it implies a choice
‘sorry’ because it does not help fix the problem
‘valid’ and ‘invalid’ because they do not add anything to the message
humourous, informal language like ‘oops’
Do not give an example in the error message if there is an example on the screen. For example, if you are asking for a National Insurance number and include ‘QQ 12 34 56 C’ as hint text, do not include an example in the error message.
Above all, aim for clarity.
Read the message out loud to see if it sounds like something you would say.
Be consistent
Use the same message next to the field and in the error summary so they:
look, sound and mean the same
make sense out of context
reduce the cognitive effort needed to understand what has happened
Use the question or form label in the error to provide context. For example, ‘Enter how many hours you work a week’ for ‘How many hours do you work a week?’
Be specific
General errors are not helpful to everyone. They do not make sense out of context. Avoid messages like:
‘An error occurred’
‘Answer the question’
‘Select an option’
‘Fill in the field’
‘This field is required’
Different errors need different messages. For example, text fields may be:
empty
too long
too short
using characters that are not allowed
in the wrong format
An error for a specific situation is more helpful. It will tell someone what has happened and how to fix it.
Use instructions and descriptions
Some errors work better as instructions and some work better as descriptions. For example:
‘Enter your first name’ is clearer, more direct and natural than ‘First name must have an entry’
‘Enter a first name that is 35 characters or less’ is wordier, less direct and natural than ‘First name must be 35 characters or less’
‘Enter a date after 31 August 2017 for when you started the course’ is wordier, less direct and natural than ‘Date you started the course must be after 31 August 2017’
Use both instructions and descriptions, but use them consistently. For example, use an instruction for empty fields like ‘Enter your name’, but a description like ‘Name must be 35 characters or less’ for entries that are too long.