Error messaging
Use error messaging to inform the user of problems on a form and provide direction on how to fix them.
-
Content:
@use '@ontario-digital-service/ontario-design-system-global-styles/dist/styles/scss/1-variables/spacing.variables' as spacing; @use '@ontario-digital-service/ontario-design-system-global-styles/dist/styles/scss/1-variables/colours.variables' as colours; @use '@ontario-digital-service/ontario-design-system-global-styles/dist/styles/scss/1-variables/global.variables' as globalVariables; .ontario-error-messaging { display: flex; align-items: flex-start; margin: (spacing.$spacing-1 * -1) spacing.$spacing-0 spacing.$spacing-2 spacing.$spacing-0; color: colours.$ontario-colour-dark-red; max-width: globalVariables.$standard-width; } .ontario-error-messaging__content { margin-left: spacing.$spacing-2; } .ontario-input__error { border-color: colours.$ontario-colour-dark-red !important; } .ontario-checkboxes__single-option .ontario-checkboxes__error { .ontario-checkboxes__label:before { border-color: colours.$ontario-colour-dark-red; } }
- URL: /components/raw/error-messaging/error-messaging.scss
- Filesystem Path: fractal/components/components/form/error-messaging/error-messaging.scss
- Size: 957 Bytes
-
Content:
.ontario-error-messaging{display:flex;align-items:flex-start;margin:-0.25rem 0 .5rem 0;color:#d81a21;max-width:48rem}.ontario-error-messaging__content{margin-left:.5rem}.ontario-input__error{border-color:#d81a21 !important}.ontario-checkboxes__single-option .ontario-checkboxes__error .ontario-checkboxes__label:before{border-color:#d81a21}
- URL: /components/raw/error-messaging/error-messaging.css
- Filesystem Path: fractal/components/components/form/error-messaging/error-messaging.css
- Size: 340 Bytes
Guiding principle: Help the user be successful the first time.
On this page
When to use this component
Error messaging indicates to users that an action was unsuccessful.
For example, if a user incorrectly completes a field or skips a mandatory field, the application should notify the user with an error message. The error message should explain what the error was and how to correct it in specific, clear, human-friendly language.
There are three main principles to follow when using error messaging in your forms:
- error messages should be easy to understand
- error messages should be easy to notice
- fields with errors should be easy to locate
If a user submits a form that contains errors, the form should be returned and indicate the errors using:
- an error summary at the top of the page
- inline errors next to the erroneous fields
Example
Form validation methods
There are two methods for validating forms and providing error messaging:
- server-side validation (required)
- client-side validation
Server-side validation
Server-side validation is required for all forms, even if you also use client side validation. Without server-side validation, invalid inputs could be submitted if JavaScript was disabled.
Client-side validation
Client-side validation uses scripting languages, such as JavaScript. The benefits are that users receive feedback quicker —- no need to go off to the server, process the information, then download another HTML page.
If you use client-side validation, make sure your client-side and server-side validation rules do not conflict.
Error summary
An error summary is a page alert that indicates to users that the action was unsuccessful and gives a high-level summary of the fields where the errors have occurred.
Providing an error summary at the top of the page is good practice for accessibility, and you should use it even if there is only one validation error.
Best practices
Do
- always place an error summary at the top of the page. Make sure it is above the top level heading (
h1
) - use “There is a problem” as a heading at the top of the error summary
- add “Error: “ to the beginning of the page
<title>
so screen readers read it out as soon as possible - when the new page or view is first loaded, ensure that focus is moved to the error summary
- add
role="alert"
to the error summary container - tell the user how to correct mistakes, and remind them of any format requirements
- Include an in-page anchor link to the corresponding form control to make it easier for users to get to the error they need to fix.
- Make sure the anchorlink in the error message in the summary matches the inline form element error message.
Inline errors
Inline errors appear directly above the invalid input field.
They tell the user:
- what went wrong and why (indicate a specific problem)
- how they can fix it (provide direction and appropriate actions)
Inline errors should be shown when a user:
- leaves a required input field blank
- enters an incorrect format in the input field
- leaves a required radio button or checkbox group unselected
Best practices
Do
- be clear, concise and specific
- use positive, plain and helpful language
- provide direction and appropriate actions to users
- indicate the problem (what went wrong), cause (why) and solution (how user can fix it)
- place the error text directly above the form input or group (and after hint text, if there is any)
Don’t
- blame the user
- use tooltips to display errors
- use all uppercase text in error messaging
- clear the fields if there was an error
- display inline error text below or beside the form input
- turn on HTML5 validation (the visual style, placement and content of HTML5 error messages may be inconsistent across browsers/devices and is not consistent with the design system)
Contact us
If you have any questions or feedback, please get in touch.