Displaying custom errors

The CRM Helper Framework automatically handles displaying validation errors in a GOV.UK-compliant error summary. In most cases, the default behaviour works without any additional configuration. However, there are scenarios where you need to display errors in a custom location.

Default error handling

By default, the ValidateData function looks for an element with the ID error-summary-container and displays the error summary there. This element is already included in the base layout templates, so you do not need to add it yourself.

When validation fails, the framework automatically:

• displays the GOV.UK error summary with links to each invalid field
• adds error messages below each invalid field
• adds the error styling to form groups
• moves focus to the error summary for screen reader users

Using a custom error container

If your form is not on the main page (for example, inside a modal or a separate section), you can specify a different error container by passing a CSS selector as the second parameter to ValidateData.

// Default - uses #error-summary-container
const isValid = DfEPortal.ValidateData(inputObj);

// Custom - uses a different container
const isValid = DfEPortal.ValidateData(inputObj, "#modal-error-container");

Make sure your custom container element exists in the HTML:

<div id="modal-error-container"></div>

Manually displaying errors

Sometimes you need to display error messages that are not related to form validation, for example after a failed API call or when business logic conditions are not met.

The framework provides three helper functions for manually managing errors:

ShowErrorSummary

Makes the error summary container visible.

// Show the default error summary
DfEPortal.Errors.ShowErrorSummary();

// Show a custom error summary
DfEPortal.Errors.ShowErrorSummary("#modal-error-container");

AddErrorSummaryDetail

Adds an error message to the error summary. The first parameter is the ID of the element to link to (for the error summary link), and the second is the error message.

// Add to default error summary
DfEPortal.Errors.AddErrorSummaryDetail("submit-btn", "There was a problem submitting your application.");

// Add to custom error summary
DfEPortal.Errors.AddErrorSummaryDetail("feedback-submit", "Please tell us what went wrong.", "#modal-error-container");

FocusErrorSummary

Moves keyboard focus to the error summary. This is important for accessibility so screen reader users are informed of the errors.

// Focus the default error summary
DfEPortal.Errors.FocusErrorSummary();

// Focus a custom error summary
DfEPortal.Errors.FocusErrorSummary("#modal-error-container");

Complete example

Here is an example of manually displaying an error after a failed business logic check:

try {
  const result = await DfEPortal.WebApi.CallCloudFlow(flowApiId, queryData);

  if (result.applicationExists) {
    // Show a custom error - application already exists
    DfEPortal.Errors.ShowErrorSummary();
    DfEPortal.Errors.AddErrorSummaryDetail("check-btn", "An application for your organisation already exists.");
    DfEPortal.Errors.FocusErrorSummary();
    return;
  }

  // Continue with success flow...

} catch (error) {
  // Show a generic error
  DfEPortal.Errors.ShowErrorSummary();
  DfEPortal.Errors.AddErrorSummaryDetail("check-btn", "There was a problem. Please try again.");
  DfEPortal.Errors.FocusErrorSummary();
}

When to use custom error containers

Use a custom error container when:

• your form is inside a modal or dialog
• you have multiple forms on the same page
• the default error summary position is not appropriate for the user journey

Feedback component example

A common use case is the feedback component. On GOV.UK, the feedback form appears in a panel that expands when users click "Is this page useful?". If the feedback form has validation errors, they should appear within that panel, not at the top of the main page.

In this scenario, add an error container inside the feedback panel:

<div class="dfe-feedback__form-panel">
  <div id="feedback-error-container"></div>

  <!-- Feedback form fields -->
  <div class="govuk-form-group">
    <label class="govuk-label" for="feedback-comments">
      How could we improve this page?
    </label>
    <textarea class="govuk-textarea" id="feedback-comments" name="feedback-comments"></textarea>
  </div>

  <button type="submit" id="feedback-submit" class="govuk-button">
    Send feedback
  </button>
</div>

Then pass the custom container to ValidateData:

const feedbackInput = [{
  identifier: "feedback-comments",
  type: "text-area",
  friendlyName: "your feedback",
  required: true
}];

const isValid = DfEPortal.ValidateData(feedbackInput, "#feedback-error-container");

if (isValid) {
  // Submit feedback...
}