Government of Ontario
Français

Ontario Design System

Error messaging

In progress

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

Diagram of a form page showing the placement of an error summary at the top of the screen and inline errors above individual text inputs.

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.