Principality of KaharagiaDesign System

Recover from validation errors

Help users understand what went wrong and how to fix validation errors in forms.

When to use this pattern

Show validation errors when users:

  • leave required fields empty
  • enter data in the wrong format
  • enter data that doesn't meet requirements
  • enter conflicting information

How it works

When a user submits a form with errors:

  1. Show an error summary at the top of the page
  2. Show individual error messages next to each field
  3. Move focus to the error summary
  4. Update the page title to indicate there are errors

Error summary

Show an error summary box at the top of the form, before the first field.

<div class="alert alert-error" role="alert" aria-labelledby="error-summary-title" tabindex="-1">
  <h2 id="error-summary-title">There is a problem</h2>
  <ul>
    <li><a href="#full-name">Enter your full name</a></li>
    <li><a href="#email">Enter an email address in the correct format</a></li>
  </ul>
</div>

Individual field errors

Show the error message between the label and the input field. Add a red left border to the field group.

Enter your full name
<div class="form-group form-group-error">
  <label class="form-label" for="full-name">Full name</label>
  <span class="form-error" id="full-name-error">
    Enter your full name
  </span>
  <input
    class="form-input form-input-error"
    id="full-name"
    type="text"
    aria-describedby="full-name-error"
  >
</div>

Date input with error

What is your date of birth?For example, 27 3 1990Date of birth must include a year

Writing error messages

Good error messages:

  • Are specific about what's wrong
  • Tell users how to fix the problem
  • Use plain language
  • Are concise (one sentence)
  • Do not blame the user

Examples

Instead ofUse
Invalid inputEnter your full name
Error: field requiredEnter your email address
Format incorrectEnter a date of birth in the correct format, like 27 3 1990
Must be a valid emailEnter an email address in the correct format, like name@example.com

Page title

When there are errors, update the page title to start with "Error:"

Error: Full name - Apply for a passport - GOV.KAHARAGIA

Accessibility

  • Use role="alert" on the error summary
  • Move focus to the error summary on page load
  • Use aria-describedby to link errors to inputs
  • Make error summary links go directly to the fields
  • Use colour AND text/icons to indicate errors (not just colour)

Preventing errors

Before implementing error handling, try to prevent errors by:

  • Using clear labels and hint text
  • Showing format examples
  • Using appropriate input types
  • Breaking complex questions into simpler ones
  • Only asking for information you need

Related components