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 text field with an error

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' }

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: Choose the department you’ll be working in

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

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-welcome-pack-reference-number-field-error">
          Enter the reference number you received in your welcome pack
        </a>
      </li>
      <li>
        <a data-turbolinks="false" href="#person-welcome-pack-received-on-field-error">
          Enter the date you received your welcome pack
        </a>
      </li>
      <li>
        <a data-turbolinks="false" href="#person-welcome-lunch-choice-field-error">
          Select a lunch choice for your first day
        </a>
      </li>
      <li>
        <a data-turbolinks="false" href="#person-department-id-field-error">
          Choose the department you'll be working in
        </a>
      </li>
    </ul>
  </div>
</div>
<h2 class="govuk-heading-l">
  Register your interest in becoming a teacher
</h2>
<div class="govuk-form-group govuk-form-group--error">
  <label for="person-welcome-pack-reference-number-field-error" class="govuk-label govuk-label--s">
    What is your reference number?
  </label>
  <span class="govuk-error-message" id="person-welcome-pack-reference-number-error">
    <span class="govuk-visually-hidden">
      Error: 
    </span>
    Enter the reference number you received in your welcome pack
  </span>
  <input id="person-welcome-pack-reference-number-field-error" class="govuk-input govuk-input--width-10 govuk-input--error" aria-describedby="person-welcome-pack-reference-number-error" type="text" name="person[welcome_pack_reference_number]" />
</div>
<div class="govuk-form-group govuk-form-group--error">
  <fieldset class="govuk-fieldset" aria-describedby="person-welcome-pack-received-on-error">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--s">
      <h1 class="govuk-fieldset__heading">
        When did you receive your welcome pack?
      </h1>
    </legend>
    <span class="govuk-error-message" id="person-welcome-pack-received-on-error">
      <span class="govuk-visually-hidden">
        Error: 
      </span>
      Enter the date you received your welcome pack
    </span>
    <div class="govuk-date-input">
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="person-welcome-pack-received-on-field-error">
            Day
          </label>
          <input id="person-welcome-pack-received-on-field-error" class="govuk-input govuk-date-input__input govuk-input--width-2 govuk-input--error" name="person[welcome_pack_received_on(3i)]" type="text" pattern="[0-9]*" inputmode="numeric">
        </div>
      </div>
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="person_welcome_pack_received_on_2i">
            Month
          </label>
          <input id="person_welcome_pack_received_on_2i" class="govuk-input govuk-date-input__input govuk-input--width-2 govuk-input--error" name="person[welcome_pack_received_on(2i)]" type="text" pattern="[0-9]*" inputmode="numeric">
        </div>
      </div>
      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="person_welcome_pack_received_on_1i">
            Year
          </label>
          <input id="person_welcome_pack_received_on_1i" class="govuk-input govuk-date-input__input govuk-input--width-4 govuk-input--error" name="person[welcome_pack_received_on(1i)]" type="text" pattern="[0-9]*" inputmode="numeric">
        </div>
      </div>
    </div>
  </fieldset>
</div>
<div class="govuk-form-group govuk-form-group--error">
  <label for="person-department-id-field-error" class="govuk-label govuk-label--s">
    Which department will you work in?
  </label>
  <span class="govuk-error-message" id="person-department-id-error">
    <span class="govuk-visually-hidden">
      Error: 
    </span>
    Choose the department you'll be working in
  </span>
  <select id="person-department-id-field-error" class="govuk-select govuk-select--error" aria-describedby="person-department-id-error" name="person[department_id]">
    <option value="1">
      Sales
    </option>
    <option value="2">
      Marketing
    </option>
    <option value="3">
      Finance
    </option>
  </select>
</div>
<div class="govuk-form-group govuk-form-group--error">
  <fieldset class="govuk-fieldset" aria-describedby="person-welcome-lunch-choice-error">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--s">
      <h1 class="govuk-fieldset__heading">
        What would you like for lunch on your first day?
      </h1>
    </legend>
    <span class="govuk-error-message" id="person-welcome-lunch-choice-error">
      <span class="govuk-visually-hidden">
        Error: 
      </span>
      Select a lunch choice for your first day
    </span>
    <div class="govuk-radios" data-module="govuk-radios">
      <div class="govuk-radios__item">
        <input id="person-welcome-lunch-choice-field-error" aria-describedby="person-welcome-lunch-choice-1-hint" class="govuk-radios__input" type="radio" value="1" name="person[welcome_lunch_choice]" />
        <label for="person-welcome-lunch-choice-field-error" class="govuk-label govuk-label--s govuk-radios__label">
          Salad
        </label>
        <span class="govuk-hint govuk-radios__hint" id="person-welcome-lunch-choice-1-hint">
          Lettuce, tomato and cucumber
        </span>
      </div>
      <div class="govuk-radios__item">
        <input id="person-welcome-lunch-choice-2-field" aria-describedby="person-welcome-lunch-choice-2-hint" class="govuk-radios__input" type="radio" value="2" name="person[welcome_lunch_choice]" />
        <label for="person-welcome-lunch-choice-2-field" class="govuk-label govuk-label--s govuk-radios__label">
          Jacket potato
        </label>
        <span class="govuk-hint govuk-radios__hint" id="person-welcome-lunch-choice-2-hint">
          With cheese and baked beans
        </span>
      </div>
    </div>
  </fieldset>
</div>