Ontario.ca homepage
Français

Ontario Design System

Our npm namespace has changed. Developers should update their projects to continue accessing our components.

Error messaging

Use error messaging to inform the user of problems on a form and provide direction on how to fix them.

  • Content: 
    @use '@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/spacing.variables' as spacing;
@use '@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/colours.variables' as colours;
@use '@ongov/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: 903 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.

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.

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)

Form validation methods

Validation may take place at different stages of a user’s interaction with a form.

Overview of form validation methods
Live validation Pre-submission validation Post-submission validation
When it happens When the user’s focus leaves a field after interacting with it After the user takes a “continue” or “submit” action, but before the form is submitted to the server When the form is submitted to the server
How it is implemented Client-side (JavaScript) Client-side (JavaScript) Server-side
Where error information is presented
  • In-line error
    		•
  • In-line error
  • Error summary
    		•
  • In-line error
  • Error summary
    		•
    Required or recommended Recommended only where it adds value Recommended Required

    Live validation

    This validation technique happens immediately after a user completes an input. It may improve the user experience of complicated fields or long forms.

    Conduct research and testing to help determine if you should use it. Learn more about live validation.

    Pre-submission validation

    This validation technique happens before a user submits an input to a server.

    For example, if the user selects the “submit” button on an online form and there are input errors, the error messaging will be dynamically written to the page directly.

    The benefit is that users receive feedback quicker — there’s no need to connect to the server, process the information, then download another HTML page.

    Pre-submission validation uses client-side scripting languages, such as JavaScript. The user inputs are validated by the user client or browser.

    Show an error summary above the form and have the user focus return to it.

    Set the focus to the error message with client-side scripting using JavaScript focus().

    If you use pre-submission validation, make sure your client-side and server-side validation rules do not conflict.

    Post-submission (server-side) validation

    Post-submission validation happens after a user submits an input to a server.

    Server-side validation is required for all forms, even if you also use client-side validation.

    For example, when a user selects the “submit” button on an online form, this action is processed by a server-side scripting language. The feedback is then sent back to the user with a new dynamically generated web page.

    Without server-side validation, a user could submit invalid inputs if JavaScript was disabled.

    If you have any questions or feedback, please get in touch.