DEV Community: Colette Wilson

How I approach keyboard accessibility for modals in React

Colette Wilson — Sun, 13 Jun 2021 11:39:00 +0000

A couple of disclaimers before I start:

This is not an article on how to manage modals in React, this article is about ensuring that modals are accessible for keyboard users.
I am not an accessibility expert and, therefore, there may be things that could be better.

TL;DR

The Basic Markup

For this demonstration, I have used the useState React hook to set and unset the display state of my modal. Since my components are very simple it’s fairly easy to pass that state from the Page component containing the trigger button directly to the Modal component. In reality, you might use some sort of state management library to do this, I like Zustand, but that’s off-topic. So, to start with my modal component looks like this;

const Modal = ({ close modal }) => {

  return (
    <aside 
      className="modal"
      role="dialog"
      aria-modal="true"
    >
      <div className="modalInner">
        <button className="modalClose" type="button" onClick={closeModal}>
          <span className="visuallyHidden">Close modal</span>
        </button>
        <main className="modalContent">
          ...
        </main>
      </div>
    </aside>
  )
}

As you can see I have an aside, this acts as a fullscreen background, a div acting as the modal container, a button to close the modal, and a main element containing the content. The modal trigger button on the Page component simply sets the display state to true, this state is then used to display or hide the Modal component. The close button resets the display state to false.

This works perfectly well for mouse users so what’s the problem? Well, at the moment the modal opens on top of the page content without updating the DOMs active element, in other words, the focus will remain on the last focused item somewhere on the page behind the modal, leaving a keyboard user unable to interact with any elements inside the modal. Obviously not ideal so how can we make this more accessible?

Focus Trapping

The answer is to trap the focus in the modal while active. Essentially we need to add some Javascript that will ensure we add focus to the modal so the user can tab around and that they aren’t able to tab away from the modal without first closing it.

The first thing I'm going to do is create a new handleKeydown function. This function will listen for a keypress and where appropriate invoke a further function that will perform a specific action, it looks like this;

// map of keyboard listeners
const keyListenersMap = new Map([
  [9, handleTab],
])

const handleKeydown = evt => {
  // get the listener corresponding to the pressed key
  const listener = keyListenersMap.get(evt.keyCode)

  // call the listener if it exists
  return listener && listener(evt)
}

Here I have a map of key codes and corresponding functions. It's not necessary to structure things this way but I find it easier if I ever need to extend functionality later. handleKeydown listens to the key code of the key that's been pressed then gets and invokes the appropriate function from the map if there is one.

To start with the only key I'm tracking in my map has a key code of 9, the tab key. When tab is pressed the handleTab function should be invoked which looks like this;

const handleTab = evt => {
  let total = focusableElements.length

  // If tab was pressed without shift
  if (!evt.shiftKey) {  
    // If activeIndex + 1 larger than array length focus first element otherwise focus next element
    activeIndex + 1 === total ? activeIndex = 0 : activeIndex += 1

    focusableElements[activeIndex].focus()

    // Don't do anything I wouldn't do
    return evt.preventDefault()
  }

  // If tab was pressed with shift
  if (evt.shiftKey) {
    // if activeIndex - 1 less than 0 focus last element otherwise focus previous element
    activeIndex - 1 < 0 ? activeIndex = total - 1 : activeIndex -= 1

    focusableElements[activeIndex].focus()

    // Don't do anything I wouldn't do
    return evt.preventDefault()
  }
}

There's quite a lot going on here so let's break it down. The first line stores the total number of focusable elements as a variable. This just helps to make things a little more readable. focusableElements is a variable that has been set in a useEffect hook. We'll come to this later. Next, I want to detect whether or not the tab button was pressed in combination with shift. This will determine the direction we cycle through the elements. If just tab was pressed, no shift, we want to cycle forward. I'm using a ternary operator to set the index either to the next item in the array of focusable elements or, if there are no more elements in the array, back to the first element. This way we'll be able to tab infinitely without ever leaving the modal. activeIndex is a variable which on initial load is set to -1. And finally, I need to apply focus to the item in the focusableElements array at the correct index. The final line return evt.preventDefault() is a safety net just to ensure nothing unexpected happens.

When tab is pressed with shift we need to repeat this cycle but in the other direction. So this time the ternary operator will set the index to the previous item in focusableElements unless we're at the beginning of the array in which case it will set the index to the last item in the array.

To get everything hooked up I'm going to use 2 separate React useEffect hooks. The first will query for all the relevant elements within the modal and update the focusableElements variable. Note: The list of queried elements is not exhaustive, this is a small example and you may need to update the list depending on the content of the modal. The second will attach the event listener that will fire the handleKeydown function described above;

React.useEffect(() => {
  if (ref.current) {
    // Select all focusable elements within ref
    focusableElements = ref.current.querySelectorAll('a, button, textarea, input, select')
  }
}, [ref])

React.useEffect(() => {
  document.addEventListener('keydown', handleKeydown)

  return () => {
    // Detach listener when component unmounts
    document.removeEventListener('keydown', handleKeydown)
  }
}, [])

As you can see this is where I update the focusableElements variable. I'm using a ref which is attached to the div acting as the modal container so that I can collect all the elements within it. It's not strictly necessary to do this within the useEffect in my example since the content is static but in a lot of cases, the modal content may be dynamic in which case the variable will need to be updated whenever the component mounts.

Closing the Modal

One thing I want to do is to extend my map of key codes to include detection for the escape key. Although there is a button specifically for closing the modal it's kind of a hassle to always have to cycle through all the elements to get to it. It would be nice to allow a user to exit early. So when the escape key is pressed I want to invoke the handleEscape function to close the modal. First I need to extend the keyListenersMap to include the additional key code, it now looks like this;

const keyListenersMap = new Map([
  [27, handleEscape],
  [9, handleTab],
])

Then I need to add the new handleEscape function, which in this example look like this;

const handleEscape = evt => {
  if (evt.key === 'Escape') closeModal()
}

Technically I could call closeModal from the map instead of wrapping it in another function but IRL I often need to do other things in here, for e.g. resetting a form or some other form of clean up.

The final thing I need to do is return focus to the page when the modal closes. First I need to know which element is the currently active element at the time the modal is mounted. When the component mounts I want to set an activeElement variable, const activeElement = document.activeElement on my Modal component. When the component unmounts I simply want to return the focus to that same element. I'm going to update the same useEffect hook where my event listener is attached and detached. In the return function I'm simple going to add, activeElement.focus() so that the useEffect now looks like this;

React.useEffect(() => {   
  document.addEventListener('keydown', handleKeydown)

  return () => {
    // Detach listener when component unmounts
    document.removeEventListener('keydown', handleKeydown)
    // Return focus to the previously focused element
    activeElement.focus()
  }
}, [])

There you have it. A modal that is keyboard friendly.

A couple of things not covered by this blog that you might consider adding as 'nice to haves';

Stopping the background page scroll while the modal is active
Closing the modal on a background click.

How I approached keyboard accessibility on my site navigation

Colette Wilson — Wed, 01 Jul 2020 13:55:18 +0000

Cover photo by Jay Zhang on Unsplash

A couple of disclaimers before I start:

This is not a how-to. I'm not suggesting this is how keyboard accessibility should be handled, this is just an article on how I approached it.
I am not an expert in accessibility and there will most certainly be things I've done here that could be better.

The Basic Markup

Let's take a look at some basic markup as a starting point. Typically, I might start off with something that looks like this;

<header class="header">
  <nav class="nav">
    <ul class="nav__list">
      <li class="nav__item has-dropdown">
        <span>Item 1</span>
        <ul class="nav__dropdown">
          <li><a href="">Sub item 1</a></li>
          <li><a href="">Sub item 2</a></li>
          <li><a href="">Sub item 3</a></li>
        </ul>
      </li>
      <li class="nav__item has-dropdown">
        <span>Item 2</span>
        <ul class="nav__dropdown">
          <li><a href="">Sub item 1</a></li>
          <li><a href="">Sub item 2</a></li>
          <li><a href="">Sub item 3</a></li>
        </ul>
      </li>
      <li class="nav__item has-dropdown">
        <span>Item 3</span>
        <ul class="nav__dropdown">
          <li><a href="">Sub item 1</a></li>
          <li><a href="">Sub item 2</a></li>
          <li><a href="">Sub item 3</a></li>
        </ul>
      </li>
      <li class="nav__item"><a href="">Item 4</a></li>
    </ul>
  </nav>
</header>

As you can see I have a list of navigation items some of which have sub items which I would like to be presented as dropdowns.

In my accessibility ignorant past I was satisfied with handling the display of those dropdowns purely through CSS simply by declaring display: none; on the dropdown then targeting the parent <li> on hover and switching to display: block;.

As I now know this approach renders those dropdowns completely inaccessible to keyboard users. How do I fix this?

Improving the Markup with Attributes

Currently there are a number of problems with the markup as it is. First off, the list items with dropdowns are not keyboard navigable. This is because some HTML elements come with built in roles, examples of these are buttons or anchor tags. Since my list items contain a span, an element that doesn't come with a role, there is no reason for the keyboard to tab to that item. Secondly, even if I could tab to these items the dropdown is only shown on hover so at the moment I can only access those dropdowns as a mouse user.

The first step in making my navigation more keyboard friendly is to add some additional markup in the form of attributes.

Firstly, let's give the nav element a label. I might have more than one type of nav element across the website, for example, the footer might contain a nav element or I might have some pagination within a nav element. It would be nice to announce what the navigation is for. To do this I'm going to add aria-label="Main".

Secondly, although <li> is an example of an element that comes with a built in role I want to specify a role that is more accurate of what these elements actually are so I'm going to add role="menuitem" to my <li>s.

Thirdly, I need to be able to tab to my <li>s. For this I'm going to add tabindex="0" to the items that contain a dropdown. Giving the attribute a value of zero allows that element to become focusable sequentially in keyboard navigation.

Lastly, I want to add a couple more attributes that it make clear that this item has a popup which is currently not expanded so I also want to add aria-haspopup="true" aria-expanded="false" to my list items containing a dropdown.

The markup for my list items now looks like this;

<li class="nav__item has-dropdown" role="menuitem" aria-haspopup="true" aria-expanded="false" tabIndex="0">
  <span>Item 1</span>
  <ul class="nav__dropdown">
    <li><a href="">Sub item 1</a></li>
    <li><a href="">Sub item 2</a></li>
    <li><a href="">Sub item 3</a></li>
  </ul>
</li>

Great, now I'm able to tab through my main navigation items but how do I get to the dropdowns?

Adding Some Javascript

At this point I should say that there is a CSS solution to this problem. By using the :focus-within pseudo-class I could add display: block; to the <li> should one of the links within that item receive focus. This may be appropriate for smaller nav structures but my project featured a structure that I felt was a little too complex and I decided it was best to employ an alternative solution.

Firstly, I want to target all the list items that have a dropdown. I could do this with const navItems = document.querySelectorAll(".nav__item.has-dropdown"), however, I prefer to separate my css from my js and to make it clear that there is javascript attached to these items I'm going to add a js specific class of js-nav-item. Now that I have them stored as a variable I can loop over them and add a keydown event listener which will invoke a function called handleKeydown. My handleKeydown function will look like this;

const handleKeydown = (evt) => {
  if (evt.keyCode === 13) {
    evt.preventDefault()
    evt.currentTarget.setAttribute("aria-expanded", "true")
    evt.currentTarget.querySelector("a").focus()
  }

  if (evt.keyCode === 27) {
    evt.currentTarget.setAttribute("aria-expanded", "false")
    evt.currentTarget.focus()
  }
}

This function listens for a key press and if the key code matches the code for the Enter key will change the value of the aria-expanded attribute to true. It will also find the first <a> within the list item and give it focus. If the key code matches the code for the Escape key it will change the value of the aria-expanded attribute to false and will return the focus to the navigation item.

Great but at this point my dropdown still won't actually display. I need to update my CSS to target the aria-expanded attribute and set display: block; when true. Like so,

.nav__item.has-dropdown[aria-expanded="true"] .nav__dropdown {
  display: block;
}

This is good progress. I can tab through my nav items, I can open the dropdown by pressing Enter, and I can close the dropdown by pressing Escape. However, although I can tab through the links in the dropdown on Chrome, Firefox will just tab to the next top-level nav item -- I need to be able to cycle through the dropdown links somehow. Also, if I tab to next top-level item without first closing the dropdown it will remain open. I also want the dropdown to close when the focus is not on it's parent.

Let's tackle the dropdown links. It would be nice if, when the dropdown is open, I could cycle through the links using the arrow keys. To do this I'm going to expand my handleKeydown function. I want to be able to select the dropdown in my js so, as before, I want to add a js specific class of js-nav-dropdown to all the dropdown elements. Now, I can get all the links within the dropdown and add a keydown event listener which will invoke a handleDropdownKeydown function. My updated handleKeydown function now looks like this;

const handleKeydown = (evt) => {
  if (evt.keyCode === 13) {
    evt.preventDefault()
    evt.currentTarget.setAttribute("aria-expanded", "true")
    evt.currentTarget.querySelector("a").focus()

    // Target dropdown and call function to cycle through dropdown links
    let dropdown = evt.currentTarget.querySelector(".js-nav-dropdown")
    handleDropdownKeydown(dropdown)
  }

  if (evt.keyCode === 27) {
    evt.currentTarget.setAttribute("aria-expanded", "false")
    evt.currentTarget.focus()
  }
}

And my handleDropdownKeydown function looks like this;

const handleDropdownKeydown = (parent) =>  {
  const links = parent.querySelectorAll("a")
  links.forEach((el, i) => {
    el.addEventListener("keydown", (evt) => {
      if (evt.keyCode === 40 || evt.keyCode === 39) {
        let next = links[i + 1] || null
        evt.preventDefault()
        next !== null && next.focus()
      }
      if (evt.keyCode === 38 || evt.keyCode === 37) {
        let prev = links[i - 1] || null
        evt.preventDefault()
        prev !== null && prev.focus()
      }
      if (evt.keyCode === 13) {
        evt.stopPropagation()
      }
    })
  })
}

In this function I am selecting all the links within the dropdown and looping over each of them to add a keydown event listener. If the keyCode for the event is 40 (up arrow) or 39 (right arrow) I want to add focus to the next link. If the keyCode is 38 (down arrow) or 37 (left arrow) I'd like to add focus to the previous link. If the keyCode is 13 (Enter key) I want the link to take me to it's destination, however, in my handleKeydown function I have prevented the default action. Because of event bubbling this means that pressing Enter when focused on a dropdown link won't do anything so I need to invoke the stopPropogation() method. Excellent, now I can cycle through the dropdown links and they will function as expected.

The very last thing I want to do is to close the dropdown if the focus moves on to another top-level nav item. To do this I want to loop over my nav items and add a focus event listener which will call a handleFocus function. handleFocus will loop over all the items and update the aria-expanded attribute to false which will close any open dropdowns.

That's pretty much it.

DEV Community: Colette Wilson

How I approach keyboard accessibility for modals in React

Contents:

TL;DR

The Basic Markup

Focus Trapping

Closing the Modal

How I approached keyboard accessibility on my site navigation

Contents:

The Basic Markup

Improving the Markup with Attributes

Adding Some Javascript