Allow disabling autofocus on error summary

Make it possible to disable the autofocus behaviour on the error summary by setting a data attribute on the module (or by setting disableAutoFocus if using the Nunjucks macro). This is consistent with the approach currently used for the notifcation banner.

The main use case for this is on the Design System, where the auto focus is problematic for the examples provided within the guidance – it causes the browser to scroll down to the first example on the page. At the minute, we are working around this by 'monkey-patching' the init method to remove the call to $module.focus [1].

[1]: alphagov/govuk-design-system#643

src/govuk/components/error-summary/error-summary.js

@@ -22,6 +22,10 @@ ErrorSummary.prototype.init = function () {
 ErrorSummary.prototype.setFocus = function () {
   var $module = this.$module
 
+  if ($module.getAttribute('data-disable-auto-focus') === 'true') {
+    return
+  }
+
   // Set tabindex to -1 to make the element programmatically focusable, but
   // remove it on blur as the error summary doesn't need to be focused again.
   $module.setAttribute('tabindex', '-1')

src/govuk/components/error-summary/error-summary.test.js

@@ -22,6 +22,24 @@ describe('Error Summary', () => {
     expect(tabindex).toBeNull()
   })
 
+  describe('when auto-focus is disabled', () => {
+    it('does not have a tabindex attribute', async () => {
+      await page.goto(`${baseUrl}/components/error-summary/autofocus-disabled/preview`, { waitUntil: 'load' })
+
+      const tabindex = await page.$eval('.govuk-error-summary', el => el.getAttribute('tabindex'))
+
+      expect(tabindex).toBeNull()
+    })
+
+    it('does not focus on page load', async () => {
+      await page.goto(`${baseUrl}/components/error-summary/autofocus-disabled/preview`, { waitUntil: 'load' })
+
+      const activeElement = await page.evaluate(() => document.activeElement.dataset.module)
+
+      expect(activeElement).not.toBe('govuk-error-summary')
+    })
+  })
+
   const inputTypes = [
     // [description, input id, selector for label or legend]
     ['an input', 'input', 'label[for="input"]'],

src/govuk/components/error-summary/error-summary.yaml

@@ -36,6 +36,10 @@ params:
     type: object
     required: false
     description: HTML attributes (for example data attributes) to add to the error link anchor.
+- name: disableAutoFocus
+  type: boolean
+  required: false
+  description: Prevent moving focus to the error summary when the page loads.
 - name: classes
   type: string
   required: false
@@ -183,3 +187,8 @@ examples:
       -
         text: Descriptive link to the <b>question</b> with an error
         href: '#error-1'
+- name: autofocus disabled
+  hidden: true
+  data:
+    titleText: There is a problem
+    disableAutoFocus: true

src/govuk/components/error-summary/template.njk

@@ -1,5 +1,6 @@
 <div class="govuk-error-summary
   {%- if params.classes %} {{ params.classes }}{% endif %}" aria-labelledby="error-summary-title" role="alert"
+  {%- if params.disableAutoFocus %} data-disable-auto-focus="true"{% endif %}
   {%- for attribute, value in params.attributes %} {{ attribute }}="{{ value }}"{% endfor %} data-module="govuk-error-summary">
   <h2 class="govuk-error-summary__title" id="error-summary-title">
     {{ params.titleHtml | safe if params.titleHtml else params.titleText }}