Focus skip link target to improve screen reader announcements

Based on alphagov/govuk-frontend#2450

Author: colinrotherham

CHANGELOG.md

@@ -83,6 +83,7 @@ We've made fixes to NHS.UK frontend in the following pull requests:
 - [#1148: Fix Tabs component in Safari < 14 and Internet Explorer 11](https://github.com/nhsuk/nhsuk-frontend/pull/1148)
 - [#908: Updating secondary, reverse and warning buttons to use their hover variable rather than darkening the base colour](https://github.com/nhsuk/nhsuk-frontend/pull/908)
 - [#1169: Update visually hidden behaviour to match GOV.UK Frontend](https://github.com/nhsuk/nhsuk-frontend/pull/1169)
+- [#1173: Focus skip link target to improve screen reader announcements](https://github.com/nhsuk/nhsuk-frontend/pull/1173)
 
 ## 9.3.0 - 13 February 2025
 

packages/components/skip-link/_skip-link.scss

@@ -13,3 +13,18 @@
   padding: nhsuk-spacing(2);
   @include visually-hidden-focusable; // [1]
 }
+
+.nhsuk-skip-link-focused-element {
+  &:focus {
+    // Remove the native visible focus indicator when the element is
+    // programmatically focused.
+    //
+    // We set the focus on the linked element (this is usually the <main>
+    // element) when the skip link is activated to improve screen reader
+    // announcements. However, we remove the visible focus indicator from the
+    // linked element because the user cannot interact with it.
+    //
+    // A related discussion: https://github.com/w3c/wcag/issues/1001
+    outline: none;
+  }
+}

packages/components/skip-link/skip-link.js

@@ -1,3 +1,5 @@
+import { setFocus } from '../../common.js'
+
 /*
  * NHS.UK skip link.
  *
@@ -6,23 +8,37 @@
  */
 
 export default () => {
-  // Assign required DOM elements
-  const heading = document.querySelector('h1')
-  const skipLink = document.querySelector('.nhsuk-skip-link')
+  const $skipLink = document.querySelector('.nhsuk-skip-link')
 
-  const addEvents = () => {
-    // Add tabindex = -1 and apply focus to heading on skip link click
-    skipLink.addEventListener('click', (event) => {
-      event.preventDefault()
-      heading.setAttribute('tabIndex', '-1')
-      heading.focus()
-    })
-    // Remove tabindex from heading on blur
-    heading.addEventListener('blur', (event) => {
-      event.preventDefault()
-      heading.removeAttribute('tabIndex')
-    })
+  // Check for skip link
+  if (!$skipLink || !($skipLink instanceof HTMLAnchorElement)) {
+    return
   }
 
-  if (heading && skipLink) addEvents()
+  const linkedElementId = $skipLink.hash.split('#').pop()
+  const $linkedElement = linkedElementId
+    ? document.getElementById(linkedElementId)
+    : null
+
+  // Check for linked element
+  if (!$linkedElement) {
+    return
+  }
+
+  /**
+   * Focus the linked element on click
+   *
+   * Adds a helper CSS class to hide native focus styles,
+   * but removes it on blur to restore native focus styles
+   */
+  $skipLink.addEventListener('click', () =>
+    setFocus($linkedElement, {
+      onBeforeFocus() {
+        $linkedElement.classList.add('nhsuk-skip-link-focused-element')
+      },
+      onBlur() {
+        $linkedElement.classList.remove('nhsuk-skip-link-focused-element')
+      }
+    })
+  )
 }

tests/integration/jsdom/skip-link.test.js

@@ -3,71 +3,82 @@ import SkipLink from '../../../packages/components/skip-link/skip-link.js'
 // Mock HTML
 const skipLinkHtml =
   '<a class="nhsuk-skip-link" href="#maincontent">Skip to main content</a>'
-const headingHtml = '<h1>Test Heading</h1>'
+const mainHtml = '<main class="nhsuk-main-wrapper" id="maincontent"></main>'
 
-// DOM Elements to be set
-let skipLink
-let heading
+/** @type {HTMLElement | null} */
+let main = null
+
+/** @type {HTMLAnchorElement | null} */
+let skipLink = null
 
 // Helper to set DOM Elements
 const initTest = (html = '') => {
   document.body.innerHTML = html
-  heading = document.querySelector('h1')
   skipLink = document.querySelector('.nhsuk-skip-link')
+  main = document.querySelector('main')
   SkipLink()
 }
 
 describe('NHS.UK skiplink', () => {
   describe('Does not throw an error', () => {
     it('if no skiplink exists', () => {
-      initTest(headingHtml)
-      expect(heading).toBeDefined()
+      initTest(mainHtml)
       expect(skipLink).toBeNull()
+      expect(main).toBeDefined()
     })
 
-    it('if no heading exists', () => {
+    it('if no main content exists', () => {
       initTest(skipLinkHtml)
       expect(skipLink).toBeDefined()
-      expect(heading).toBeNull()
+      expect(main).toBeNull()
     })
 
-    it('if no skiplink or heading exists', () => {
+    it('if no skiplink or main content exists', () => {
       initTest()
-      expect(heading).toBeNull()
       expect(skipLink).toBeNull()
+      expect(main).toBeNull()
     })
   })
 
-  describe('Focuses the heading on skiplink click', () => {
-    it('if skiplink and heading elements exist', () => {
-      initTest(skipLinkHtml + headingHtml)
-      expect(skipLink).toBeDefined()
-      expect(heading).toBeDefined()
+  describe('Focuses main content on skiplink click', () => {
+    it('if skiplink and main element exist', () => {
+      initTest(skipLinkHtml + mainHtml)
+
+      // Main content not focused
+      expect(main).not.toEqual(document.activeElement)
+      expect(main.getAttribute('tabIndex')).toBeNull()
+      expect(main.classList.value).not.toContain(
+        'nhsuk-skip-link-focused-element'
+      )
 
       skipLink.click()
 
-      expect(heading.getAttribute('tabIndex')).toBe('-1')
-      expect(document.activeElement).toEqual(heading)
+      // Main content focused
+      expect(main).toEqual(document.activeElement)
+      expect(main.getAttribute('tabIndex')).toBe('-1')
+      expect(main.classList.value).toContain('nhsuk-skip-link-focused-element')
     })
   })
 
-  describe('Unfocuses the heading on blur', () => {
-    it('if skiplink and heading elements exist', () => {
-      initTest(skipLinkHtml + headingHtml)
-      expect(skipLink).toBeDefined()
-      expect(heading).toBeDefined()
+  describe('Unfocuses main content on blur', () => {
+    it('if skiplink and main element exist', () => {
+      initTest(skipLinkHtml + mainHtml)
 
       skipLink.click()
 
-      expect(heading.getAttribute('tabIndex')).toBe('-1')
-      expect(document.activeElement).toEqual(heading)
+      // Main content focused
+      expect(main).toEqual(document.activeElement)
+      expect(main.getAttribute('tabIndex')).toBe('-1')
+      expect(main.classList.value).toContain('nhsuk-skip-link-focused-element')
 
-      heading.blur()
+      main.blur()
 
-      expect(heading.getAttribute('tabIndex')).toBeNull()
-      expect(document.activeElement).not.toEqual(heading)
+      // Main content not focused
+      expect(main).not.toEqual(document.activeElement)
+      expect(main.getAttribute('tabIndex')).toBeNull()
+      expect(main.classList.value).not.toContain(
+        'nhsuk-skip-link-focused-element'
+      )
     })
   })
-
-  describe('Is initialised by nhsuk.js', () => {})
 })