Skip to main content

This is a guide on using the GOV.UK Design System Form Builder

  1. Index
  2. Error handling

Error handling

When a form is submitted and there is a problem, communicating that problem in a clear and concise manner is imperative. The form builder provides two ways to do this.

Error messages are displayed immediately above the offending field. They should tell the user how to fix the problem.

Additionally a summary of all the problems with the submission should be displayed at the top of the page. Every error in the summary is a hyperlink that when followed focusses on the problematic field.

This behaviour is provided by the form builder without any need for extra configuration.

A form with multiple errors

Input

= f.govuk_error_summary

h2.govuk-heading-l
  | Register your interest in becoming a teacher

= f.govuk_text_field :welcome_pack_reference_number,
  width: 10,
  label: { text: 'What is your reference number?', size: 's' }

= f.govuk_date_field :welcome_pack_received_on,
  legend: { text: 'When did you receive your welcome pack?', size: 's' }

= f.govuk_collection_select :department_id,
  departments,
  :id,
  :name,
  label: { text: 'Which department will you work in?', size: 's' }

= f.govuk_collection_radio_buttons :welcome_lunch_choice,
  lunch_options,
  :id,
  :name,
  :description,
  legend: { text: 'What would you like for lunch on your first day?', size: 's' }
<%= f.govuk_error_summary %>
<h2 class="govuk-heading-l">
  Register your interest in becoming a teacher
</h2>
<%= f.govuk_text_field :welcome_pack_reference_number, width: 10, label: { text: 'What is your reference number?', size: 's' } %>
<%= f.govuk_date_field :welcome_pack_received_on, legend: { text: 'When did you receive your welcome pack?', size: 's' } %>
<%= f.govuk_collection_select :department_id, departments, :id, :name, label: { text: 'Which department will you work in?', size: 's' } %>
<%= f.govuk_collection_radio_buttons :welcome_lunch_choice, lunch_options, :id, :name, :description, legend: { text: 'What would you like for lunch on your first day?', size: 's' } %>

Rendered output

Register your interest in becoming a teacher

Error: Enter the reference number you received in your welcome pack
When did you receive your welcome pack? Error: Enter the date you received your welcome pack
Error: Select the department to which you’ve been assigned
What would you like for lunch on your first day? Error: Select a lunch choice for your first day
Lettuce, tomato and cucumber
With cheese and baked beans

Linking errors on the base object to specific fields

Some errors don’t apply to a specific field but the object as a whole. The GOV.UK Design System guidelines suggest that in this case, the error summary link should take the user to the first field. As the form builder doesn’t know the order in which fields will be rendered, it must be specified.

Input

= f.govuk_error_summary link_base_errors_to: :email_address

= f.govuk_email_field :email_address, label: { text: "Email address" }
= f.govuk_phone_field :telephone_number, label: { text: "Phone number" }
<%= f.govuk_error_summary link_base_errors_to: :email_address %>
<%= f.govuk_email_field :email_address, label: { text: "Email address" } %>
<%= f.govuk_phone_field :telephone_number, label: { text: "Phone number" } %>

Rendered output

HTML output

<div class="govuk-error-summary" tabindex="-1" role="alert" data-module="govuk-error-summary" aria-labelledby="error-summary-title">
  <h2 id="error-summary-title" class="govuk-error-summary__title">
    There is a problem
  </h2>
  <div class="govuk-error-summary__body">
    <ul class="govuk-list govuk-error-summary__list">
      <li>
        <a data-turbolinks="false" href="#person-email-address-field">
          Enter a telephone number or email address
        </a>
      </li>
    </ul>
  </div>
</div>
<div class="govuk-form-group">
  <label for="person-email-address-field" class="govuk-label">
    Email address
  </label>
  <input id="person-email-address-field" class="govuk-input" type="email" name="person[email_address]" />
</div>
<div class="govuk-form-group">
  <label for="person-telephone-number-field" class="govuk-label">
    Phone number
  </label>
  <input id="person-telephone-number-field" class="govuk-input" type="tel" name="person[telephone_number]" />
</div>