Tooltips have been a reliable source of web accessibility woes from the very beginning; or at least from the beginning of graphical web browsers. They have gone by many names: "tooltip," "infotip," "toggle tip," "hint text," "balloon help," "info bubble," "inaccessible overlay of shame"... the list goes on. No matter the name, the same core issues just keep popping up:

• How do keyboard users access the content?
• How do non-mouse pointers (e.g. touchscreens and eye trackers) access the content?
• How do blind and low vision users even know the tooltip is there, let alone read it?
• If (Internet Lords forbid) there is interactive content inside, how does one access it without accidentally dismissing the tooltip?
• How does a user with magnification software move their field of view to read the tooltip without accidentally dismissing it?

So why do tooltips have so many problems?

The first hint of a graphical tooltip on the web came in an early draft of HTML when "title" appeared as an optional attribute on links with the following note:

The browser software may chose to display the title of the document as a preliminary to retrieving it, for example as a margin note or on a small box while the mouse is over the anchor, or during document fetch.

At the time that spec was written, graphical screen readers had already existed for over four years. Now, 26 years in the future, we're doing a little bit better. The same inaccessible mouse-based title behavior exists, but at least the latest version of the HTML spec explicitly calls out the accessibility problems while warning against using it. Also, WCAG is a thing now. But back in the earlier days of the web, it was open season on defining experiences solely for sighted mouse users.

The image tag was first proposed by a browser representative (from Mosaic, since this happened in 1993) as more of an advance notice than a suggestion. Although the alt attribute was included in the img specification from the very start, practical support was slow and for years screen readers and text-only browsers had no good way of communicating a graphic.

If the history of the image tag seems like an odd digression for an article about tooltips, the reason lies in what happened next: browsers began to actually implement the alt attribute, but they chose to visually display it as a tooltip, just like the title attribute on links. Although alt still functioned as a text alternative, the tooltip implementation changed how website authors wrote alt text content. There are articles written about the harmful effect of the tooltip treatment as well a compilation of hilarious examples of real live alt text from that time (imagine image after image with the alt text "Click here!").

Although alt text no longer gets the tooltip treatment in any modern browser, looking back at that era illustrates a deeper issue with the design itself. From the very beginning, the behavior of a native tooltip has made it easy to create content solely for mouse users with good vision while forgetting about everyone else. The alt text tooltip directly demonstrated how easily that type of design can degrade the experience for anyone relying on non-mouse-based interaction or assistive tech. Continuing problems caused by the title attribute's non-inclusive tooltip have also been thoroughly documented (try this wonderfully comprehensive 24a11y article by Scott O'Hara for a start).

Beyond the title attribute: what are tooltips now?

Usually "use native controls" is the mantra of accessibility professionals, so if the native tooltip is flawed all the way down to its very design, where does that leave designers and developers? The short answer is out in the rain without a popup (or "umbrella" for those who live in the real world) for shelter.

Before diving into the details of how to implement a custom tooltip, let's take a moment to define what a tooltip really is. Conventionally, the term has referred to a purely visual treatment: text that appears in a small overlay on demand, usually when hovering over the thing it describes. This presents a problem when trying to create a specification for a consistent, accessible experience, since visual patterns do not always have a one-to-one relationship with interaction patterns.

(Wait. What?)

A major pitfall of approaching web design as a visual medium is conflating visual patterns with functional or interaction patterns. One classic example of this is that the word "menu" in web UI has acquired both a broad, generic meaning as well as a specific and technical one. In what passes for casual conversation among web professionals, the word "menu" might refer to a set of links used as site navigation, the file/edit/etc. bar of actions along the top of most applications, or a list of appetizers printed on paper at a restaurant.

Leaving off that last one, keyboard and assistive tech users expect a navigation menu and traditional application menu to function differently: a navigation menu is a list of links that is tabbed through, and an application menu is a collection of menu actions that are reached by arrow keys and often shortcuts. One visual pattern, multiple interaction patterns. To go further down that particular rabbit hole, try this shot: inclusive-components.design/menus-menu-buttons followed by this chaser: github.com/w3c/aria-practices/issues/353.

(Back to tooltips)

Much like "menu," the word "tooltip" has come to mean nearly any small, non-modal overlay. While the most traditional use is to provide simple hint text for UI controls (tips for tools, after all), the same visual pattern could be used to display a text alternative for an icon button, a form error message, rich text content (e.g. bold text or a list), or even interactive content. Although all of these use cases could share the same base implementation if visual presentation and mouse interaction were all that mattered, the differences are important for accessibility for the following reasons (in order):

1. Hint text is purely supplemental, and should not override the existing accessible name for a control.
2. The text alternative for an icon button is its accessible name, and should be associated with the button accordingly.
3. Rich text formatting can not be conveyed through the usual means of associating hint text with a control (namely aria-describedby).
4. Interactive content within a popup introduces a whole new set of requirements. It must be easily discoverable by screen readers, follow a logical tab order, be easy to access without dismissing the tooltip and without relying on fine motor control.

There is no single DOM structure or javascript implementation that could fill all the requirements of even the few use cases mentioned here, so for the purposes of arriving at some sort of concrete recommendation, popups with rich or interactive content are not considered tooltips. Those patterns would benefit from using a disclosure button pattern under the hood. Similarly, a tooltip-style popup that is not tied to an existing interactive control would also benefit from the disclosure pattern. This would prevent it from spawning a useless button purely for the purpose of introducing a tab stop for keyboard access.

With those out of the way, let's take a stab at writing a visually-agnostic spec for a tooltip. The rest of the article, particularly the accessibility recommendations, will assume that a tooltip fits the following definition:

A "tooltip" is a non-modal (or non-blocking) overlay containing text-only content that provides supplemental information about an existing UI control. It is hidden by default, and becomes available on hover or focus of the control it describes.

That definition could even be narrowed down even further by saying tooltips must provide only descriptive text -- essentially defining it as a custom, accessible version of the title attribute -- but all of the same interaction requirements apply whether the tooltip is used to display a name, description, or error message even if the semantics differ slightly.

The accessibility requirements of tooltips

Tooltips must be discoverable and readable with a mouse, other pointer devices, keyboard, screen reader, zoom software, and any other assistive technology. They should provide relevant information that may be helpful to learn the UI, but is not required to operate it. Tooltips also should not block a user from performing any other task on the screen.

Not so complicated, right? Let's dive into some of the specifics, broken down into semantics, interaction, and content.

Semantics

Meaningful semantics form the backbone of good HTML structure, and help screen readers and other assistive tech provide so many helpful shortcuts for moving around an interface. Headings are headings, links are links, accordions let you know if they are expanded or collapsed, and tooltips are... what exactly?

As described in detail earlier, tooltips can be used for a number of purposes. Even in our stripped-down definition, they could function as a name or a description, and the semantics would be different for each. The trick is to first decide what purpose the tooltip text has, and then assign semantics accordingly.

Descriptive tooltip semantics

For the most canonical tooltip purpose -- hint text -- the only two semantic additions are:

1. associate the tooltip trigger with the tooltip via aria-describedby and id
2. ensure the tooltip is unreachable when hidden via aria-hidden

A full HTML snippet for a sample text field asking for a name, with hint text in a tooltip follows. This HTML snapshot assumes the tooltip is in an open state.

<label for="name">Full Name</label>
<input id="name" type="text" aria-describedby="name-hint">
<div id="name-hint" aria-hidden="false">
  Please enter your given name followed by your family name
</div>

Label tooltip semantics

Using a tooltip as the accessible name is similar; instead of aria-describedby, the association would be made with aria-labelledby, and the tooltip container would not necessarily need aria-hidden. It is also possible to drop aria-labelledby entirely and have the tooltip text be a child of the control (at least for controls that support children). The main caveat for the name use case is that UI controls should always have some sort of label visible. This technique would not replace the need for a visible label next to an input, for example. A good use would be to add a text alternative for icon buttons.

Semantics to avoid

There are certain attributes that are missing in the above descriptions that the more ARIA-conscious may have already noticed. In no particular order, these are some accessibility-related attributes that may seem relevant, but are not currently recommended:

• role="tooltip": the unloved child of roles, this omission is perhaps the weirdest in an article specifically about tooltips. While it's not a bad idea to add it to the tooltip element, it doesn't seem to do much good either. The tooltip role does not appear to affect screen reader announcements in any meaningful way -- aria-describedby and aria-labelledby do all the heavy lifting. If you do decide to add it, use it only for descriptive tooltips along with aria-describedby. There is more context in this Github thread: github.com/w3c/aria/issues/979
• aria-haspopup: although a tooltip may visually look like a popup, this attribute is for more interactive popups -- specifically only menus, listboxes, trees, grids, and dialogs are allowed in conjunction with aria-haspopup. Using a generic value of aria-haspopup="true" will be interpreted as if it were aria-haspopup="menu". Since tooltips are not intended to be interacted with or navigated to, aria-haspopup should not be used to indicate a tooltip.
• aria-live: as the ultimate fallback for communicating any sort of dynamic page change, aria-live can be a tempting solution to complaints of tooltip text not being read by screen readers. However, live regions have some significant drawbacks for tooltip use: they can not be reliably re-read by a screen reader user, they may interrupt other content (e.g. announcing the name of the control on focus), and a screen reader user can't opt out of hearing them. It's true that aria-describedby may or may not be announced depending on a number of factors including user-selected verbosity settings, but that is the desired behavior for hint text.

Interaction

The interaction support for displaying, hiding, and reading the tooltip content is the same whether the tooltip is used for a control's name or description.

Focus and hover

The first step is to ensure that the visual display can be controlled by either a keyboard or a mouse. To do this, the tooltip should open on focus or mouse over, and closes on blur or mouse out. Combining pointer and keyboard events should not create multiple tooltips or other buggy behavior. Since the UI control associated with the tooltip presumably has some sort of default action on click/enter or space/input, those interactions are not available for use in displaying or hiding the tooltip. If the UI control does not perform any actions or accept user input, it probably shouldn't have a tooltip at all (see the disclosure button pattern instead).

Pointer (lack of) access

Now that phone browsing has taken over, providing touch access has become imperative and this also benefits users of other non-mouse pointer device such as eye trackers. Unfortunately, one of the major drawbacks to tooltips is that they are inaccessible to touch devices when attached to buttons or links. This is because hover is unavailable on a touch device, and it is also impossible to focus a button or link without activating it. The same limitation exists for other pointer-controlled assistive tech like eye gaze. There is currently no workaround, although tooltips on form inputs will still work as expected.

WCAG 2.1: dismissable, hoverable, and persistent

One of the rules added in the Web Content Authoring Guildelines (WCAG) update from 2.0 to 2.1 is the 1.4.13: Content on Hover or Focus criterion. This new guideline expands the work required to make a compliant tooltip, but should make overlays in general significantly more accessible and less disruptive. WCAG 2.1 requires any content appearing on hover or focus to be dismissable, hoverable, and persistent.

To achieve those, a tooltip should:

• Hide when a keyboard user presses "Escape" (unless the tooltip will never overlap other content).
• Allow a mouse or pointer user to hide the tooltip, ideally through a close button (unless the tooltip will never overlap other content). The tooltip should not re-appear on subsequent hovers -- think of a zoom user trying to center their view on a specific area without triggering the tooltip and obscuring content.*
• Allow a mouse user to move their mouse over the tooltip content without dismissing the tooltip -- ideally in a manner that does not require laser focus and precision mouse control.
• Remain in view until the user actively dismisses it, or it is no longer valid (e.g. if a loading tooltip appeared, then it could disappear after the content loaded).

An extra note for those who closely read WCAG: "unless the tooltip will never overlap other content" is less of an exception than it appears. Even if a tooltip does not appear to overlay other content at a certain screen size, it may do so at a different screen size or level of zoom.

(*) An even more nitpicky side note: WCAG 1.4.13 says that a tooltip should be dismissable "without moving pointer hover or keyboard focus," then goes on to suggest the Escape key to fulfill this requirement. This makes sense for keyboard users, but not at all for mouse users. On a usability level, people who primarily rely on a mouse or pointer are less likely to know keyboard shortcuts, and may not be able to use them. On a technical level, it is impossible to capture an escape press on a control that is hovered but not focused. A global escape listener would not be able to differentiate between a user wanting to dismiss a tooltip vs. close a dialog, if one were open. In short, the only feasible solution is to provide both keyboard and pointer methods of dismissal.

Content

Tooltips should only ever contain non-essential content. The best approach to writing tooltip content is to always assume it may never be read. As mentioned above, touch devices and other alternative pointers can't reach tooltips on buttons or links, and screen readers sometimes ignore descriptive text by default. It should be possible to infer how to use the UI without reading any tooltips. If that is not the case, it would be best to move all necessary content out of tooltips and into an area with more robust access and discoverability.

In addition to writing only supplemental content, the following should also be true:

• Write concise tooltip text. Imagine someone on a small screen or with high zoom needing to pan around just to read the tooltip.
• Avoid rich content. Formatting such as bold text, italics, headings, icons, etc. will not be conveyed through aria-describedby or aria-labelledby.
• No interactive content. Any interactive content such as links or buttons should not be placed within a tooltip.

Best practices summary

• Only interactive elements should trigger tooltips
• Tooltips should directly describe the UI control that triggers them (i.e. do not create a control purely to trigger a tooltip)
• Use aria-describedby or aria-labelledby to associate the UI control with the tooltip. Avoid aria-haspopup and aria-live
• Do not use the title attribute to create a tooltip
• Do not put essential information in tooltips
• Provide a means to dismiss the tooltip with both keyboard and pointer
• Allow the mouse to easily move over the tooltip without dismissing it
• Do not use a timeout to hide the tooltip

If this article leaves you hungry for more tooltip drama and intrigue, never fear. You can continue your journey into tooltip mastery by perusing any of the links under "Further reading." Also: get involved! Comment on this W3C tooltip issue with thoughts, questions, and concerns to influence the future of expected tooltip behavior.

Code samples

Here is a simple Codepen example, also viewable without the code editors as a full page pen. Scott O'Hara also has a much more comprehensive, documented example on github.

Further reading:

• www.24a11y.com/2017/the-trials-and-tribulations-of-the-title-attribute
• ebay.gitbook.io/mindpatterns/disclosure/tooltip
• inclusive-components.design/tooltips-toggletips
• a11yproject.com/posts/title-attributes
• developer.paciellogroup.com/blog/2013/01/using-the-html-title-attribute-updated

Why? I had used the escape key to collapse a select menu, and ended up closing the modal dialog containing the entire expense form instead. This happened because the select menu really should have been a <select>, but wasn't. Instead it was a custom dropdown, and whoever made it remembered that dropdowns should dismiss on escape, but didn't test that behavior in context. So of course, being an a11y-focused developer, my immediate response was to put off finishing the expense report and start writing a blog post about the escape key instead.

Why escape?

When starting out on the long, pothole-ridden journey to better keyboard accessibility, the three most common pit stops along the road (the Shell, BP, and Chevron, if you will) are Enter/Space, arrow keys, and escape. There are other keys, of course -- Home, End, PageUp, PageDown all make appearances as the occasional drive-through coffee stand or 2am IHOP.

Then there are accesskeys, the weird roadside attractions of accessibility: you periodically see signs for them, but almost never actually visit. In the general run of things, however, a developer working on custom keyboard handling for the web will generally spend the most time on these keys:

• Enter or Space: perform the primary action of the control.
• Arrow keys: move focus to the previous or next control, when appropriate.
• Escape: exit the current context.

Enter, Space, and arrow keys are all fairly predictable. By that I mean it is very rare to encounter uncertainty from either the developer or the user around what should happen when the spacebar is pressed.

...and please don't come at me with your split buttons or selectable editable tree items, write your own article ;)

This is a slight oversimplification, but: some combination of enter and space perform the primary action of the currently focused control, and arrow keys shift focus in one or two dimensions.

Escape, on the other hand, is a little trickier. It has become an all-purpose "get me out of here!" key; something like array.pop() but for UI contexts.

When should you escape?

(Or: what do I mean when I say "UI context"?)

Part 1: Overlays

In its simplest incarnation, a new context is created when an overlay opens and fully or partially covers some other stuff (technical term) in the same window. When this happens, escape should allow the user to return to their previously un-obscured view. Almost all of the definitions of escape-based interactions in the Aria Authoring Practices fall in this bucket:

• Combobox
• Modal dialog
• Menu
• Tooltip

A few more overlays you may find yourself needing to escape from:

• Slidepanes
• Non-modal dialogs (e.g. disclosure buttons with popups)
• Custom context menus

Generally overlays are pretty easy to recognize. Anything that appears on top of the regular flow of the document, whether modal or non-modal, interactive or not, counts as an overlay and should be easy to dismiss. See the WCAG 2.1 content on hover or focus criterion, or my earlier long tooltip ant article for more context on why.

Part 2: Tab traps

The most common example of a tab trap was already covered in the previous section -- the modal dialog. However, there are other examples of UI elements that block tabbing without visually breaking the page flow:

• A rich text editor or code editor: tabbing within these inserts an actual tab character, so there needs to be another way of exiting and moving past them.
• Too many tab stops: counter-intuitively, too many focusable items can also effectively block keyboard navigation. Imagine a table with 50 rows and a few interactive items per row; it would take a lot of patience to get through 100+ tab stops. A skip link at the beginning would help someone who wants to bypass the table entirely, but not someone who wants to browse through the table's data and then either return to the beginning of the table (maybe there are filters or other controls there), or skip past remaining rows.

Part 3: Cancel changes

This category of escapable contexts has nothing to do with page navigation, and everything to do with editing content. Any interface that allows the user to switch between reading and editing (like a cell within an editable grid) should provide the option to cancel all changes and return to the read mode at any point when editing.

If edit mode vs. read mode is a full page change (for example, the github gist editor), then a cancel button makes more sense than escape for switching back to read mode. However, for in-place edits (for example, changing a single cell within an editable grid) it makes sense to allow the user to hit escape to cancel and return to read mode.

So you've escaped. Now what?

(Or: where should focus go next?)

Some popups like combobox menus and tooltips never take focus, so no active focus handling needs to occur when they are dismissed.

Other popups should take focus when opened -- modal dialogs, modal slidepanes, some menus -- and should send focus back to the element that originally opened the popup when closed. If that element no longer exists, it gets a bit trickier. The ARIA Authoring Practices Guide has a long note on focus handling when closing modals. The short version is: take a second to think about where the user would expect to be, and send focus there.

Start by putting yourself in your users' frame of mind

It's also possible to put focus in different places depending on how a modal is closed: for example, a modal form that creates a new table row may move focus to that row when submitted. Even if this type of logic exists, closing via escape should take the user back to the original trigger button.

Our third category, non-modal tab traps, are a little harder. Escape should jump the user out of the tab trap but there's no obvious place to put focus, and the user shouldn't end up immediately re-entering the tab trap on the next tab or shift + tab. There's no way of knowing whether the user intends to move forwards or backwards after exiting, so you can't simply place focus before or after the trap. Combining escape with a skip link can be a powerful workaround, which is what this grid example does.

Handling conflicts when escaping

(stopPropagation: Just Do It™)

When handling escape key event listeners within an application, it's important to always stop the event from propagating. This prevents multiple nested components from all trying to respond to the same escape, so a user trying to dismiss a toolitp or combobox menu within a modal won't accidentally close the modal (thus bringing us back to the original modal that kicked all this off). A well-placed event.stopPropagation() would have prevented that original bug.

A good rule of thumb when coding UI components is if you ever write a listener for a key event and do anything at all in response to the escape key, then also stop event propagation.

Example:

myCombobox.addEventListener('keydown', function(event) {
  if (event.key === 'Escape') {
    myCombobox.close();
    event.stopPropagation();
  }
});

External conflicts

It's uncommon for web apps or websites to ever run into a situation where custom escape handling might interfere with native platform behavior, but when testing with Windows screen readers it's good to know that the first escape press might cause a switch from application mode to browse mode. If this happens, the event may or may not be sent to the DOM as well -- NVDA does not send a keyboard event to the DOM when switching modes, but JAWS does. This is worth remembering, since it is entirely possible for a JAWS user to accidentally dismiss a popup when intending to switch modes. The only real workaround to this is to make escaped contexts easily recoverable -- modals and dropdowns can be re-opened, and tab traps can be re-entered. Ideally something like a modal form would either save user input if closed and re-opened or, even better, live within its own separate page.

Final Thoughts

Escape has been used to do some weird things in native applications. In Internet Explorer, escape will clear a text input; same in Microsoft Outlook for Windows and File Explorer. Browser URL bars in Windows and MacOS will not only clear input but also restore the current URL on escape. On Windows, escape lets you exit the application menu and takes you back to whatever last had focus. Pressing escape in the chat window of Microsoft Teams jumps you to the most recent message. And there are certainly more escape oddities out there, waiting to be discovered.

While many of those seem uninituitive to me, they may make sense to someone else. When venturing off the beaten path of documented patterns and simple escape behavior, the ultimate test is always a well-rounded usability study and real-world feedback.

In the meantime, check out the grid example page for a practical example containing several different uses of escape.

Now to finish that expense report...

By a play/pause toggle, I mean this thing:

i.e. that thing you click on (or key press/touch/switch/etc) to get your daily cute cat fix. You press it, it switches from a play icon to a pause icon, Maru jumps into a box, and bliss ensues.

That's where I barge in and ask about that middle part -- switching from play to pause -- and ruin it all (sorry Maru). The thing is, a play/pause button is effectively a toggle button, by which I mean it switches between two binary states based on user interaction. The established pattern for accomplishing this is by updating the aria-pressed state attribute, which accepts a true/false value.

Play/pause buttons (and by extension, start/stop buttons) are the black sheep of the toggle button family. They generally do not have any aria-pressed on/off state defined, and instead change their accessible name from "play" to "pause" when activated. When I say "generally," I mean this was true for the following sites, chosen for no formal reason other than that I happened to know they would contain media players:

• Youtube: dynamically changes aria-label
• Mixer: dynamically changes aria-label
• Vimeo: dynamically changes name from contents (by swapping out labelled graphics)
• Soundcloud: dynamically changes both text content and the title attribute
• WAI carousel tutorial: dynamically changes text content
• Twitter's media player: Twitter's media player actually has no accessible name and no state defined for its play button. Whoops.

So why does this matter? Traditional toggle buttons switch aria-pressed from true to false, and play/pause buttons change their calculated name from "play" to "pause." No big deal?

Property vs. State

Most dynamic changes to a UI component (at least, changes that happen while a user is interacting with it) are communicated through state changes rather than property changes. The ARIA spec has this to say about states vs. properties:

One major difference is that the values of properties (such as aria-labelledby) are often less likely to change throughout the application life-cycle than the values of states (such as aria-checked) which may change frequently due to user interaction. Note that the frequency of change difference is not a rule; a few properties, such as aria-activedescendant, aria-valuenow, and aria-valuetext are expected to change often.

This comes across as fairly similar to the use of states vs. properties in javascript application frameworks as well -- a common convention is that a change in application state will trigger a re-render, while a change to a property will not (unless manually triggered).

It might therefore seem reasonable to also expect a screen reader to pick up and announce state changes but not property changes. However, as with many things related to ARIA, it is not that simple.

Some properties such as aria-activedescendant, aria-valuenow, and aria-valuetext can be expected to be announced by screen readers when changed (support issues aside). Some state changes (such as aria-disabled) are not consistently announced when changed. However, as a very general rule of thumb, it is safer to assume that a change in state will be communicated than a change in property (and please never change a role during a user interaction).

Side note: when I reference changes that are announced by screen readers, I mean a change to the element that currently has focus that causes some sort of screen reader-generated feedback without the user moving focus.

Most screen readers nowadays rely on Accessibility API events to get notifications about changes to the DOM. So, for example, when aria-pressed updates from true to false a PropertyChangedEvent will fire, allowing a screen reader to listen to that event and react to it. Each platform's Accessibility API handles this slightly differently (PropertyChangedEvent is specific to UIA on Windows), but the principal is roughly the same. This list of state and property change events details which states and properties should raise API events when changed. Not all of those states and properties will necessarily be communicated by all screen readers, but these are the ones that at least have a mechanism to do so.

All this is relevant since aria-pressed is a state, and the accessible name is a property.

Name Changes

The conventional wisdom is to not change the name of a control while the user is interacting with it. It turns out this is pretty good conventional wisdom: upon testing, I found that while a name change is sometimes announced, it is not nearly consistent enough to be relied upon.

Using this button code sample, I tested whether name changes and aria-pressed changes were announced using the following screen reader/browser combinations, and using a few different methods of defining the accessible name:

Side note: NVDA, you drunk?

Actual Recommendations

You made it this far, congratulations! Time for some concrete recommendations. The big takeaway should be this:

Change the name, but not the state, of play/pause buttons. Use state for all other toggle buttons.

Why? First, because the mechanics of a play/pause (or start/stop) button are so well understood by now that immediate state change feedback is not critical.

This is combined with the fact that using aria-pressed="false" for a pause button would result in some variation of "play button off" to be read by screen readers, which is not particularly reflective of a visual pause icon. Creating a difference between the programmatic label and visual text (or icon) can cause issues for speech control users, sighted screen reader users, and effective communication between blind screen reader users and visual users (e.g. during a support call).

This one edge case does not take away the general recommendation to change the aria-pressed state, and not the name, for other toggle buttons. Toggle buttons that are part of less well-known interfaces would benefit more from providing immediate feedback, and the only reliable cross-screen-reader cross-browser way to do that is to use aria-pressed.

As a final note, never change both the name and aria-pressed state in tandem. That way, confusion lies. Just imagine trying to parse the meaning of "play button, on" vs. "pause button, off".

Further Reading

• Styled Toggle Buttons from Scott O'Hara
• Building Inclusive Toggle Buttons from Heydon Pickering
• UWP Toggle Switch description: a Windows desktop toggle pattern, for reference

1. Part 1: 24a11y.com/2019/select-your-poison
2. Part 2: 24a11y.com/2019/select-your-poison-part-2

The end result is a set of three recommended implementations for a select-only or read-only <select> variant, an editable combobox, and an editable multiselect combobox. While I highly recommend reading the recommendations in the context of the second article to get the nuances of why choices were made and what other options there are, here's the quick cheat sheet:

The links each go to a github repository of web components written using StencilJS and Typescript. There is a Codepen implementation with all three implementations written in vanilla JS.

1. Select-only combobox
2. Editable combobox
3. Multi-select

More Links

For anyone who would like to play around with all the select component variations tested for this article, they can be found in three separate codepens here:

1. All select-only variations
2. All editable combobox variations
3. All multi-select variations

Finally, the environments for the two usability studies that were run with disabled participants are available here:

1. Main combobox study
2. Additional mini ARIA 1.2 study

Talk to your kids about ARIA before it's too late.

Basic vs. composite patterns

Composite widget patterns like trees and grids differ from basic controls in both expectations for keyboard behavior and semantic structure. Re: keyboard interaction, they generally contain multiple interactive elements, but are only one stop in the tab order. Custom key handling (primarily arrow keys) is required to provide access to all interactive descendants of the container widget.

Composite widgets also have much more rigid requirements for semantic structure. While a button or a checkbox will have rules regarding what ARIA states and properties they support, they function as single isolated interactive elements. A composite widget role will also determine the allowed roles, states, and properties of its descendants. For instance, a tablist must contain only tabs, and those tabs must be its direct children. In contrast, a set of links within a navigation region could be marked up with or without a list, or four levels deep in divs without interfering with parsing the semantics of either the navigation region or the links.

We're not going to spend any time here on when and why to use a composite widget role over a group of simple interactive elements, though that is certainly an important discussion to have. Instead, let's dive straight into the accessibility tree.

The Accessibility tree: a quick definition

The accessibility tree is an internal browser construct that is used as an intermediate step between converting the DOM into the low-level accessibility APIs that screen readers (and potentially other assistive tech) consume. It is also currently distinct from the Accessibility Object Model (AOM), which is a proposed spec for an API similar to the DOM.

The per-browser instructions for inspecting the accessibility tree are below:

• Chrome and Chromium Edge
• Firefox
• Safari

Since the accessibility tree is an internal browser abstraction, there are some minor differences between browsers. For example, a plain <div> is represented as a GenericContainer in Chrome, and a section in Firefox. Still, the differences are minor and all implementations allow you to inspect which nodes exist in the accessibility tree, as well as check their calculated names, roles, values, states, and properties.

I personally prefer the Firefox Accessibility inspector, since it allows you to pick nodes from the rendered page and walk the entire accessibility tree, much like inspecting the DOM in the Elements pane.

Relationships between nodes

Composite widgets like listbox, grid, tree, etc. rely on strict parent/child and sibling relationships between accessibility nodes
to communicate calculated information about those relationships to screen reader users. Information like item position within a list, column and row information in a table or grid, and level information in a tree may be missing or incorrect if node hierarchy is not properly defined. The practical impact varies based on browser and screen reader.

Inserting an extra <div> between a table element and a row, or a row and a table cell, can break screen reader shortcuts, column header/row header/cell association, and indexing of columns and rows. This is easy to debug by inspecting the table's generated accessibility tree in the Firefox devtools accessibility pane:

All composite widget roles

Here's a list of all roles that require specific parent/child relationships to function correctly (as of ARIA 1.2):

• combobox - listbox - option (this one is slightly different, see the combobox post for specifics)
• grid - caption (optional, must be first child if used) / rowgroup (optional) - row - gridcell / columnheader / rowheader
• listbox - group (optional) - option
• menu / menubar - group (optional) - menuitem / menuitemcheckbox / menuitemradio
• radiogroup - radio
• tablist - tab
• tree - group (optional) - treeitem
• treegrid - rowgroup (optional) - row - gridcell / columnheader / rowheader

These document structure roles are not interactive, but also rely on a strict semantic hierarchy:

• associationlist - associationlistitemkey / associationlistitemvalue
• feed - article
• figure - caption (optional, must be first or last child)
• list - listitem
• table - caption (optional, must be first child if used) / rowgroup (optional) - row - cell / columnheader / rowheader

Looking up correct semantics

The ARIA spec details which roles need specific parent or child relationships, though it's easy to miss. When looking up the documentation for a role, check for entries for Required Owned Elements and Required Context Role in the role's Characteristics table. If present, the role in question must be the direct child of a required context role, and its own children must have one of the roles in required owned elements.

For example, the entry for grid notes that it can either have row or rowgroup -> row as required owned elements. Follow those links, and you can piece together what the role heirarchy should be:

• grid
  • optional: caption
  • optional: rowgroup
    • row
      • optional: rowheader
      • optional: columnheader
      • gridcell

Fixing an incorrect accessibility tree

A few techniques for repairing accessibility tree issues, once found.

1. Fix the DOM hierarchy

No ARIA is always the best ARIA. If it's possible to make the DOM structure match the desired accessibility tree structure, that is always the best and most robust solution.

2. role="presentation" or role="none"

Sometimes it isn't possible to alter the DOM structure, whether because of styling needs, support requirements, or use of external UI libraries. In those cases, it can be possible to clean up the accessibility tree through the judicious use of `role="presentation/none".

For example, the following broken tree structure:

<ul role="tree">
  <div class="item-wrapper">
    <li role="treeitem">
      Item 1
      <div role="group">
        <ul class="sub-items">
          <li role="treeitem">Sub-Item 1</li>
          <li role="treeitem">Sub-Item 2</li>
        </ul>
      </div>
    </li>
    <li role="treeitem">Item 2</li>
    <li role="treeitem">Item 3</li>
  </div>
</ul>

Could be modified to work as follows:

<ul role="tree">
  <div class="item-wrapper" role="presentation">
    <li role="treeitem">
      Item 1
      <div role="group">
        <ul class="sub-items" role="presentation">
          <li role="treeitem">Sub-Item 1</li>
          <li role="treeitem">Sub-Item 2</li>
        </ul>
      </div>
    </li>
    <li role="treeitem">Item 2</li>
    <li role="treeitem">Item 3</li>
  </div>
</ul>

You can try inspecting both in the browser in this JSFiddle.

Note that role="presentation/none" is only required on elements that come between composite widget roles. It would not be necessary to add an extra role to a <div> that is a child of treeitem, or parent of tree.

The two roles, presentation and none, are synonyms. As of writing, presentation has better support, so is slightly preferable over none.

3. aria-owns

Using aria-owns to point to the id of another element entirely separated in the DOM will establish a programmatic parent/child relationship between the two nodes in the accessibility tree.

4. display: none and visibility: hidden

CSS can sometimes affect the accessibility tree. Two examples are display: none and visibility: hidden, both of which will remove a node and all its descendents from the accessibility tree, hiding it from all users equally. If this is not desired, there are CSS techniques to visually hide content while keeping it accessible to screen readers.

Common (ish) Misconceptions

1. role="presentation" is not aria-hidden="true"

Applying aria-hidden to an element will remove that element and all its descendants from the accessibility tree entirely, while role="presentation/none" will only remove the element's default role. Both role="presentation/none" and aria-hidden="true" will have the same effect on an <img> tag, but not on an element with content or children.

2. aria-controls is not aria-owns

Even though the combobox pattern has swapped out aria-owns for aria-controls, the two are not interchangeable elsewhere. aria-owns will establish a parent-child relationship between the root node and the referenced node (though reading order will still follow DOM order). aria-controls is a bit more abstract, and has little to no practical impact; only use it for comboboxes, or optionally when the ARIA spec explicitly says it should be used.

1. Debating framework choices with a dogmatic fan, and
2. Naming things

There is seemingly no solution for the first problem; you must accept it, adopt a zen-like calm when faced with invocations of bundle sizes and performance benchmarks, and silently plan your backup career doing literally anything else.

For the second problem, naming things, it's generally best to just pick something and move on. After all, any name is better than wasting hours agonizing over whether toggleMenuItemSelection is adequately understandable, descriptive, and concise.

And then, as a counterpoint, we have sequential-focus-navigation-starting-point.

You try saying "sequential focus navigation starting point" five times over the course of two minutes, while also trying to explain to someone exactly why they still need to handle focus after closing their dropdown, even though "tabbing works in Chrome." To prove my point, here is a brief list of names I would much rather use in said calls:

• focus-start-point
• focus-bookmark
• starty-focus-party
• fast-focus
• 2-focus-2-furious
• fate-of-the-focus

Why are we talking about Something Focus Something Point?

The sequential focus navigation starting point is a browser feature that enables three types of interaction that were not possible without it:

1. You can follow an internal link to a section or heading, and then start tabbing from that section/heading
2. You can click anywhere on the page, and begin tabbing from that point
3. You can hide an element with focus, e.g. by removing it from the DOM or applying display: none, without breaking tabbing.

All three behaviors enhance user experience, but the last one in particular has sometimes lured developers into a false sense of security about not handling focus when closing their popups, dropdown menus, or accordions. Although tabbing seems to work fine in these cases, the sequenced-focus-starts-somewhere-around-here-point is only a bandaid; manual focus handling is still necessary for robust accessibility.

Where did Sequential Focus Whatever come from?

The idea of a sequential focus navigation starting point began with the need to make same-page anchors work with keyboard navigation. Although same-page linking has been available for as long as <a> elements, keyboard support has often lagged behind visual mouse support, even at a platform level. So although sighted users would immediately have access to the linked section via scroll and could then interact with it using a mouse, keyboard users would have a different experience. As soon as an internal link was activated, focus would jump to the top of the document, and the next tab press would bring you back to the first focusable element in the page.

To fix this, browsers (possibly starting with IE5) began to send focus to the link target when following a same-page link. This only works if the target is focusable, though. Thus began the long period of recommending tabindex="-1" be added to to every heading, named anchor, or other static element targeted by an internal link.

The problem is, the visual behavior of internal links still works when the link target isn't focusable, and -- let's be honest -- that's all most developers test for. There was still an opportunity for browsers to improve the keyboard accessibility of this common built-in feature.

Firefox had a solution for this in place as early as 2013, which implemented starting-something-focus-whatsit-navigation-point in all but name. Although keyboard focus would still reset to <body> after activating a link with an unfocusable target, the next tab press would move focus as if the link target had been the active element.

Internet Explorer was the only other browser that handled non-focusable link targets, though it took a different approach and simply forced the target element to receive keyboard focus even if it was otherwise unfocusable.

Chrome took a bit longer (read: three years) to come around, but did finally implement the same focus behavior as Firefox in February 2016, with one addition:

If the element pointed by sequential focus navigation starting point is removed from the document tree, a point where there was the element at would be the starting point.

To summarize: when Chrome fixed tab order for internal links, they also used the same mechanism to save the location of the last focused item, if that item was removed from the page.

Around the same time, Rob Dodson wrote what is still the most thorough, reader-friendly explanation of sequential focus navigation starting point: Removing Headaches from Focus Management, in which he also mentioned that side benefit of gracefully handling focus when active element was hidden.

Incidentally, the phrase "sequential focus navigation why is this so long starting point" first appeared in the HTML specification in November 2014, where it was defined as an optional user agent behavior.

How SFNSP works today

The HTML spec for starting focus sequentially point still notes that it is optional, but if it exists it does the following (simplified slightly):

• Is set to the position of a user's click (or more broadly "when the user indicates that it should be moved")
• Is used to determine which element should get focus when the user presses the tab key
• When a user navigates to a fragment (e.g. by clicking on a same-page link, or visiting a URL with a "#" identifier), the start point is set to the target element.

There is no mention in the spec of using focus-nav-start-point to handle keyboard navigation when the currently focused element is hidden or removed from the DOM. Despite the lack of official sanction, this behavior seems to be increasingly relied upon by web developers when closing open dialogs, dropdowns, accordions, or any other toggleable region. This conflicts with the prevailing wisdom that when removing a focused element from the DOM, an author must manually set focus on another (logical) node. However, if browsers save focus-navigation-starts-here-point where the removed element used to be, keyboard navigation seems to work fine even if focus is not handled.

As of writing, the following browsers match Chrome's behavior and set the sequential focus navigation starting point when the currently focused element is removed or hidden:

• Chrome
• Safari
• Firefox
• Edge (Chromium)

Of all the browsers on Windows and Mac that I have access to, only Internet Explorer and Edge (pre-Chromium) do not do this. You can try it out now by jumping to the next section and then hitting tab.

Overall, this is a win for accessibility. For someone relying on keyboard navigation (or any other assistive tech that navigates via focus, like switch devices), getting sent back to the top of the page every single time a developer forgot to handle focus is an enormous pain. The drawback comes when developers don't fully understand exactly what sequential-focus-belaboring-the-point does and doesn't do, or they don't notice focus bugs when keyboard testing.

Focus navigation starting point is not the same as actual keyboard focus. When focus is lost, through following an internal link or hiding a dialog, keyboard focus moves to the <body> tag. If you query document.activeElement in either of these cases, you can observe this. Alternatively, paste the following snippet into your browser console, jump to the next section and watch every focus update in real time:

document.addEventListener('focusin', () => {
   console.log('Focus moved to:', document.activeElement);
});

That difference is extremely important when using assistive tech, since screen readers (for example) do not pay attention to the internal browser concept of focus-starts-here-point. While testing with a keyboard alone may make everything seem fine, trying the same interaction while running a screen reader exposes some rough edges.

Assistive Tech support

Tests were run against this (extremely simple and not otherwise very accessible) example that contains a few accordions and a dialog, only one of which handles focus on dismissal: https://jsfiddle.net/eo8x3pcu/show.

Results

Detailed Notes:

• NVDA + Firefox: both tab and cursor navigation work from the start point, but nothing was announced on close.
• NVDA + Chrome: tab works from the start point; scan mode is flaky, and seems to start from whatever is nearest the last (x, y) position of the dismissed focused element. Nothing is announced on close.
• NVDA + Edge Chromium: tab works, but NVDA reads "document" when focus is lost.
• Narrator + Edge (pre-Chromium): tab starts again from the top, though cursor navigation starts from where the hidden content used to be. Nothing is announced on close
• Narrator + Edge Chromium: tab works, but Narrator reads "document" when focus is lost and cursor navigation starts over from the top of the page
• JAWS with all Windows browsers: tab works, but the virtual cursor starts over from the top of the page. JAWS with Firefox reads "frame" when focus is lost, and was silent with other browsers.
• VoiceOver + Safari on iOS: the VoiceOver cursor jumps somewhere weird and inconsistent (seems to track (x, y) position on screen like NVDA and Chrome), and immediately begins reading from that point. The example that handled focus works as expected.
• VoiceOver + Safari on macOS: both tab and the VoiceOver cursor both start where they should, from where focus was lost.
• Talkback on Android: the screen reader cursor jumps to the top of the page, and begins reading it from the start.
• ZoomText (without a screen reader): When focus is lost, the screen does not re-center on the correct place (most noticeable with the dialog). It works correctly when focus is actively managed.

As is (hopefully) clear, there is absolutely no consistency in how screen readers handle lost focus. At worst, the user gets no feedback about the change of context on close, and then the screen reader starts over from the top of the page. ZoomText (and potentially other assistive tech that wasn't tested) is also affected, with the screen failing to re-center somewhere useful to the user.

Scott O'hara also has support results for testing skip link focus and virtual cursor.

Solutions

The fix is easy: always manage focus when you remove the active element from the DOM!

Supplemental links:

• https://html.spec.whatwg.org/multipage/interaction.html#sequential-focus-navigation-starting-point
• https://developers.google.com/web/updates/2016/03/focus-start-point

sequential focus navigation starting point
sequential focus navigation starting point
sequential focus navigation starting point
sequential foction navigatus starting point
sequential focusing navigation start point
sequential focal navigation startus point
sequential fo-cat nappigation flop point

More recently, a greater awareness of accessibility and an increase in the use of ARIA attributes has resulted in a sort of reverse naming problem, where elements that cannot or should not be named get artificial names through ARIA. You see this in <div>'s and <span>'s with aria-label's, or links and buttons whose programmatic name has been manually defined to be different than their visible text.

While an improperly added name is a step up from a missing one, it will often give the illusion of accessibility while masking an underlying problem that remains unaddressed. Both forgetting a name entirely and adding too many names result from not understanding when and how to properly give an element a name.

What is a "name"?

There are many different terms that are used to talk about a missing or incorrect accessible name, depending on context. For images, it can be "alternative text" or "the alt attribute"; for tables, "caption"; and for form fields, we usually talk about labels. Here's a non-comprehensive list of terms and concepts that all boil down to talking about names:

• labels, the <label> element, and associating labels with form fields
• table captions
• image alt text
• the <legend> element
• an SVG <title> element
• aria-label and aria-labelledby

The reason I'm using "name" or "accessible name" to refer to all of these different concepts is because although they differ in HTML, they all end up mapping to the "name" property (or equivalent) in accessibility APIs and the browser's internal accessibility tree. For example, this screenshot shows how an <img> element's alt attribute is represented in Microsoft Edge's accessibility dev tools:

Most browsers will also let you view exactly where that computed name came from; in this case, the alt attribute:

If you wished to open up Accessibility Insights for Windows, you could see the same string defined in the image node's Name property in the underlying accessibility API.

What needs a name?

Not every element can support an accessible name, and even among those that can, not every one should. For example, a <section> element can be named with aria-label or aria-labelledby, but doing so will promote it to being a landmark, which isn't always desired. A list can also be named, though doing so is uncommon and not needed unless there's some context-specific reason for doing so. So, if some elements always need names, others may or may not benefit from a name, and others cannot be named at all, how do you know which is which?

There are a few general categories of elements that should always be named:

1. Interactive elements:
   These include all form controls, links, buttons, and also complex interactive widgets like tabs, menus, listboxes, and so on.

2. Other focusable elements:
   Although generally non-interactive elements should not be focusable, there are some exceptions like client-side routing with focus management, a modal dialog, or the target of a skip link. Anything that can receive keyboard focus, whether through tabbing or scripting, should have an accessible name.

3. Charts and graphics:
   Meaningful images, graphs, canvas visuals, and other graphical content needs to be labelled with alternative text. Images and graphics that are not meaningful should be removed from the accessibility tree: with an <img> tag, this is done with an empty alt="", and aria-hidden="true" works for other elements.

4. Landmarks and labelled form groups:
   Sets of checkboxes and radio buttons are nearly always within a form group, or a form group could contain multiple related text inputs, e.g. for a credit card. They should always have an accessible name that matches the visible group label. Traditionally this is done with the <fieldset> and <legend> elements, but can also be accomplished with role="group" and aria-label/aria-labelledby.

   Landmarks need an accessible name when there are multiple instances of the same type of landmark on a page, such as a main navigation region together with a supplementary navigation region. Generic landmarks (with role="region") always need an accessible name.

There are multiple different WCAG criteria that cover failing to give an accessible name to an element that needs one. There's Name, Role, Value for interactive controls lacking a name; Non-text content for naming, well, non-text content; Link Purpose (in context) for links with missing or poorly written names; then there's the catch-all Info and Relationships for any other scenario where meaning is implied by visual cues or context but not present programmatically.

How do you name an element?

Contrary to what you may think, naming an element involves neither a birth certificate nor the HTML name attribute. The name attribute is never directly exposed to the user, and is used only when submitting forms. Birth certificates have thus far been ignored by spec authors as a potential method for naming controls, but perhaps when web UI becomes sentient and self-propagating, we'll need to revisit that.

Right now, there are four different types of ways an element can be assigned a name: from author, from content, from encapsulation, and from legend. The last two are highly specific to certain form elements:

Name from encapsulation, using the <label> element:

<label>
  <input type="checkbox">
  This text will be the checkbox input's name
</label>

Name from legend, which sounds epic but ultimately only refers to the <legend> element:

<fieldset>
  <legend>This text will name the fieldset element, as long as the legend is the first child</legend>
  <!-- some form elements go here -->
</fieldset>

Most of the time when naming elements, you'll be using either a name from author, or name from content. Both of these techniques are likely familiar, even if the particular phrases "name from author" and "name from content" sound more like dry spec terms than actual words real people would say to each other.

"Name from content" in its simplest form means an element's accessible name comes from its text content. Take the following example of a submit button that reads "Submit" (because I am a creative person):

<button type="submit">Submit</button>

If you were to view that in a browser, you would see that the calculated name of the button is "Submit", and that the source is the button's contents:

A button with text content is a simple example; it's also possible to have non-text content contribute to an element's accessible name. In the following example, a link contains both text and an image with alt text. In it, the image gets its name from the alt attribute, and the link is named by the combination of all plain text and other named elements within it:

<a href="#">
  <img src="images/twitter-icon.png" alt="Twitter.">
  <span>Your daily source of all current-events-related anxiety.</span>
</a>

The image's alt attribute is actually an example of a name from author, nested inside the link's name from content. "Name from author" refers to assigning a name to an element directly, either by passing a string to an attribute like alt or aria-label, or through the use of an associated labeling element, like <label for="input-id">.

Some examples of defining a name from author include:

• aria-label
• aria-labelledby
• the <label> element, associated with an <input> by id
• the alt attribute on an <img>
• the <caption> element in a <table>

Some elements with roles such as table and list, or landmark roles like navigation and main, only support name from author. If these elements are given a name through aria-label or aria-labelledby, screen readers will generally read that name when the user first enters the element, and then go on to read the element's content. This is because the content exists separately from the accessible name, so both the content and the name (if provided) are read separately.

In contrast, roles that support both name from author and name from content will only ever read one or the other. If a name from author is provided, the element's content will be entirely ignored. So if we were to consider the following extremely realistic example snippet:

<button aria-label="Cats are the best">Dogs are the best</button>

The resulting button would have an accessible name of "Cats are the best", and someone using a screen reader would not encounter the string "Dogs are the best". A name from author will always override name from content, when both are supported.

There is an entire spec governing the full set of steps that browsers must take to determine the accessible name and description for any nameable or describable element. It is arcane and complex, and can generally be ignored by web developers. Here is a reduced summary of accessible name methods, ordered from what will override everything else (1) to what will only be used if no other methods are present (4):

1. aria-labelledby
2. aria-label
3. Native HTML methods: alt, the <label> element, text content
4. Fallback attributes: title and placeholder

Ideally, a single control will only be named using one method, so the exact way browsers calculate an accessible name should not matter much (unless you work on browser accessibility, in which case, thank you). Generally when in doubt, consult the accessibility information in your browser's developer tools. That will tell you both the calculated accessible name, and where it's coming from.

While there are a good number of possible ways to name a control, not all options are created equal. Rather than go into the nuances of why to choose a <label> element over aria-label here, I'd rather link to the article Adrian Roselli has already written on his priority of methods for labeling a control. The TL;DR is:

1. Native HTML techniques (the <label> element, text content, alt, etc.)
2. aria-labelledby
3. visually hidden text content
4. aria-label

His article goes into more of the reasons around why some methods are better than others, which I won't duplicate.

One last note on adding an accessible name: the name must be added directly to the element that you intend to be named. If you want to name a table using the aria-labelledby attribute, then that attribute must be on the <table> or role="table" element. Putting aria-labelledby on a parent of the table will do nothing at all.

Which elements and roles can be named?

Every ARIA role falls into one of three naming possibilities: either it must have a name, it can optionally be named, or it cannot be named at all. Throw in the different possibilities for naming (from author, from content, from encapsulation, and from legend), and it gets to be a bit too much to keep track of.

Luckily, the ARIA spec has a section listing every single role that can be named, broken down by the naming method. Roles that require names are designated with "(name required)". Here are the sections where you can find the naming information:

• Name from author
• Name from content
• Name from encapsulation
• Name from legend
• Name prohibited

The ARIA spec lists these only by role and not by element, but if you're not sure which role an element has by default, you can look it up in the HTML AAM spec. If an explicit role attribute is present, it will override the default role mapping in HTML AAM. For example:

• <button>: look up the button role
• <button role="tab">: look up the tab role

While the most common problem is for one of the "name required" roles to lack an accessible name, sometimes the reverse occurs and an element that cannot be named -- e.g. a <div> or <span> -- is given an aria-label or aria-labelledby. A couple cases where I've seen this happen include a <span aria-label="some text"> wrapping a font icon, or an aria-label added to a div in a card pattern.

Both of these examples come from good intentions, and an active attempt to create better accessibility. On the plus side, a few extra aria-label's on unnameable elements like this won't cause any negative side effects. The main danger is that the illusion of having given something an accessible name will obscure underlying issues. Usually the fix is to revisit which elements and roles should be used, or to reconsider what really needs a name.

In the case of the font icon example, the best solution would likely change the element into an image with role="img", which can then be given a name:

<span aria-label="name of icon" role="img">&#xe900;</span>

A generic wrapping <div> for something like a card pattern is more complex. Does that section of content really need its own name, separate from the content within it? If this grouping of content is important enough to be named, then it should probably be exposed as some sort of group. Would an existing HTML pattern like a list fit your use case? Is there another element or role that would fit better?

A card pattern could be exposed as a list item within a list (as Heydon does in his card pattern), or perhaps as an article role. Both those roles (listitem and article) can be given a name from author, but that doesn't mean they need one. To decide whether a name-optional element would benefit from a name in this case as in others, the best thing to do is to consider how a programmatic name will translate into actual user experience. And then, of course, check those assumptions with people who rely on assistive technologies.

How is the accessible name used by assistive tech?

The programmatically exposed accessible name is primarily used by screen readers (including screen readers with braille displays) and voice control software. Voice control software can vary a lot in whether it uses the accessible name, text content, or some combination of the two. The programmatic name is not presented directly to the user, but consumed under the hood when a user issues a command like "press submit button."

Screen readers do present the accessible name directly to the user, in a number of different ways depending on the mode of interaction and the type of element that is named:

Direct interaction

The most straightforward way a screen reader exposes the accessible name is when the user interacts directly with the named element. This can come in the form of tabbing to a focusable element like a form field, link, or button, which is often the most beginner-friendly way of using a screen reader.

Another way to directly interact with an element is to use the screen reader's virtual cursor to move through a page, using sets of commands specific to each screen reader. This will present either the accessible name of a nameable control (heading, link, button, etc.), or a text string in the case of unnameable elements (divs, paragraphs, and so on).

Container roles

There is another type of nameable element that I'm going to call container roles, which include landmark regions, forms, lists, dialogs, tables, tabpanels, and generic groups. Usually when a screen reader user navigates the page, they will enter and exit these elements without interacting with them directly (emphasis on "usually"). If named, the name will generally be read when the screen reader's cursor first enters the container role, depending on the screen reader's support for that role (test everything).

Elements list

One last way of consuming an accessible name is in an elements list. With an elements list, a screen reader user can review all elements of a particular type (e.g. links) out of context. Here's an example of what that looks like in NVDA:

The elements list is one example of when it is important to write unique, descriptive accessible names. Multiple duplicate buttons under different headings, or link names that only make sense in context will be confusing and unhelpful in the elements list.

How do you write a good name?

A developer's blog (or at least this developer's blog) is probably not the best place to look for advice on the writing process. I personally have enough trouble trying to name variables in code that no one else will ever read. Instead, try this page of writing tips from the Web Accessibility Initiative (WAI), or this video on writing good labels from Jordyn Castor at Apple.

Instead, let's go over some general accessibility tips for writing a good name:

• Avoid including the type of control in the name
  The type of control will already be communicated by screen readers. For example, naming a submit button "Submit button" will result in a redundant announcement, e.g. "Submit button button".
• Make names unique
  Unique names help screen reader users scanning controls directly without needing to examine surrounding context, and they also help sighted users by reducing the cognitive load required to determine the purpose of a control. Visually scanning an online store's buttons is easier when each has a unique name like "shop computers" and "shop laptops", and harder when all of them read "shop now". The exception is when multiple controls do the exact same thing. For example, there are two links named "card pattern" on this page, but they both go to the same URL.
• Make names easy to skim
  Concise, descriptive names are easier to quickly skim, and reduce the time required to process and comprehend each individual control. This is particularly important when many similar named items appear grouped together, such as row headers in a table, or options in a listbox. If all the names share a common string, putting the most unique, relevant information first will make them faster to skim. So a list of dates would do better as "13 April 2020" rather than "April 13, 2020".

When should you override the visual name?

Sometimes the desire to provide a unique, descriptive name to screen readers can conflict with an existing design, or lead to arguments with others whose opinions are not entirely based in a desire for accessibility. In those cases, it can be tempting to accept less-than-ideal visual labels while modifying the accessible name behind the scenes. For example, a developer tasked with improving the accessibility of an online storefront with 10 "Shop now" links might end up adding a more descriptive aria-label to each link while keeping the visual text the same:

<!-- Don't do this -->
<a href="/shop/dresses" aria-label="Shop Dresses">Shop Now</a>

This is not ideal for a number of reasons, even though on first consideration it seems to improve the screen reader experience without the uncomfortable messiness of revisiting design. Unfortunately, creating separate visual and programmatic names causes its own new set of problems.

To start with, not all screen reader users are blind. People with low vision who use some form of magnification or high contrast might use a screen reader as a supplement. Others with no visual impairments might prefer to listen to information rather than look at it for cognitive or sensory reasons. It is not all that unusual for someone to listen to the programmatic name with a screen reader while also looking at the visual label. If those two diverge, it could be jarring and cause confusion. Even fully blind screen reader users sometimes need to communicate with tech support or sighted colleagues, and separate content can make that difficult.

Different names can also cause problems for someone using a voice control software like Dragon Naturally Speaking. A Dragon user confronted with 10 "shop now" links would not be able to take advantage of the unique but invisible "shop dresses" programmatic name. In WCAG 2.1 there is a new criterion, Label in Name, specifically for improving this experience.

All this doesn't mean that there are never good reasons to create separate programmatic and visual names. In cases where the visual name is an icon or graphic, or the visual context is conveying information that cannot be easily captured as a text label, a custom programmatic name might make sense.

A good time to use hidden text or an aria-label is when you have no visible text labeling an element, but where a sighted user gets that information through visual context. One concrete example is for landmark regions of the page: you might have a main navigation menu at the top of the page, and a secondary sidebar navigation for something like content categories. The position and visual style of each navigation region tells the user its importance, and adding short accessible names like "main" and "categories" communicates that same information programmatically. Some other examples of good use cases for hidden text, an aria-label, or other non-visual label include:

• Alt text for images
• Naming an icon button
• Naming a container widget like a dialog, feed, tabpanel, or list. If a heading or other text exists that visually labels the container, aria-labelledby is a better choice than aria-label

Practical accessibility doesn't always match ideal accessibility, and there will almost certainly be times when a design or content change just isn't happening, for whatever reason. In those cases, improving the accessible name is better than nothing. Just take care to include the visual label within the accessible name (ideally at the start), and try to write something that will not cause confusion when used together with the visual text.

Tooltips, placeholders, names, and duplicate announcements

A while back, I wrote a rant small article about some of the accessibility challenges of tooltips. One section dealt with whether the tooltip should form the name or the description of the control it is attached to. Essentially, sometimes a tooltip will function visually as the accessible name (common with icon buttons) and sometimes it will provide additional descriptive text. The danger here is that using a title attribute to provide both a tooltip and an accessible description that is the same as the control's accessible name can create duplicate announcements. Sometimes. It depends.

The same inconsistent double announcements exist with a name and placeholder, although the specifics of which screen readers and browsers double up may differ. (Full disclosure: I only tested in a few screen readers to verify inconsistency, and testing results go out of date quickly in any case).

Both the title and placeholder attributes will be used as fallback sources for the accessible name, so using them that way can be a tempting way to resolve the duplicate announcement problem. However, relying on either title or placeholder as the label for a control causes many, many accessibility problems that go beyond simple programmatic support.

Seriously, don't do it:

• The Trials and Tribulations of the Title Attribute by Scott O'Hara
• Don't Rely on the Title Attribute for Accessibility by the mediacurrent team
• Using the HTML title attribute – updated March 2020 by Steve Faulkner
• Don’t Use The Placeholder Attribute by Eric Bailey
• How-to: Use placeholder attributes from the A11y Project
• placeholder - the piss-take label by Steve Faulkner
• Placeholder research from the Web Accessibility Initiative's low vision accessibility task force
• Placeholders in Form Fields Are Harmful by Kate Sherwin

Further reading

Thanks for reading this all the way to the end! I highly recommend also reading Adrian's naming article, and the AccName specification for particularly intrepid and detail-oriented developers.

• Priority of methods for labeling a control from Adrian Roselli
• Accessible name and description computation
• What's in a Name, an article by the same name from Glen Walker

A mode like invert colors will take author-set colors and transform them, which allows something like an authored background change on hover to still happen, albeit with different colors than originally defined. WHCM, in contrast, will completely ignore the authored background color. Colors on websites viewed in WHCM are determined solely based on HTML element, CSS property, and certain states (e.g. disabled). While authors still control things like whether a border exists and outline width, the colors themselves will be overridden (at least without a high contrast mode media query, covered below).

WHCM also cares not for your ARIA roles, states, or properties. Screen readers will read a <a role="button"> as a button, but to WHCM it remains a link and receives link colors. Just as a role="button" will not apply the <button> element's default browser styles, it will also not affect WHCM styles.

If the heavy-handed nature of WHCM color overrides makes bugs seem daunting or out of your control, you're not alone. However, there are often very simple solutions to most high contrast mode issues:

1. Custom focus styles + a transparent outline

Windows High Contrast Mode wantonly ignores border or background color changes and box shadows. Both common of those common custom :focus styles will be invisible in WCHM. Luckily, if the default CSS outline property doesn't give you the visual effect you want for focus states, there's a very simple fix. Instead of overriding default browser focus styles with outline: none, make it transparent instead: outline 3px solid transparent. An example using the universal * selector might look like this:

*:focus {
  background-color: rebeccapurple;
  box-shadow: 0 0 4px 1px rebeccapurple;
  outline: 3px solid transparent;
}

WHCM will override the transparent outline color, making it visible only when high contrast mode is turned on. This trick also works with transparent borders if, for example, your button has a distinct background color but no separately visible borders.

2. SVGs and currentColor

The SVG fill and stroke properties are exceptions to the rule that WHCM overrides all colors. SVG colors will be left as-is, which is great if the SVG is being used as a logo or general image, but less useful if it's intended to be a meaningful icon. This is where the CSS keyword currentColor comes in. currentColor is defined as the value for the text color property, which will be overridden by high contrast mode.

This is generally a great way to define SVG icon color if you want to make it match the surrounding text color, because then you don't need to define both color and fill separately, or separately update fill if the text color changes (e.g. on :hover). If you don't want the SVG to match the surrounding text, then you can define a unique color on the immediate parent of the SVG. Theoretically you could define color on the SVG itself, but this doesn't consistently get overridden correctly, while color on a non-SVG parent element will.

/* SVG icons within a link will be blue */
/* SVGs not in a link will be black */

body {
  color: #000;
}

a {
  color: blue;
}

svg {
  fill: currentColor;
}

3. CSS properties

The specific CSS properties used to style visual cues can make a huge difference in WHCM. For example, using only background-color to distinguish alternating rows on a table with no borders will work outside of high contrast mode, but disappear entirely within it.

Another example that comes up frequently is custom styled form controls. Sometimes UI like a text input is re-styled to remove borders and rely on a contrasting background color, or radio button and checkbox indicators are created entirely with CSS. There's no reason not to do this, but relying on either background color or transitions between different colors to indicate state can make entire components impossible to use in high contrast mode.

Adding in a change in border or outline, or using SVGs instead, will result in accessible UI in both modes without impacting the experience outside of high contrast mode.

4. Media Queries

There is a media query that has traditionally allowed developers to target Windows High Contrast Mode and override its color modifications. This is the -ms-high-contrast media query, which supports targeting any use of high contrast mode, or specifically black-on-white or white-on-black. If using this, the best practice is to reference system color keywords rather than defining colors directly, so that the user's color choices will still be respected. This would let you do something like invert the foreground/background colors of a selected list item, or apply a visible box shadow on focus.

Rather than reproduce a full guide to using the -ms-high-contrast media query, I'd suggest reading Greg Whitworth's fantastic explainer, which includes both explanation and examples.

However, this technique comes with an enormous caveat: the -ms-high-contrast media query will be retired in favor of the standards-based forced-colors media query. Forced colors has the benefit of being CSS spec, with a cross-browser cross-OS set of standardized system color keywords.

As of writing, we're in an odd in-between time when -ms-high-contrast is on its way out, and forced-colors is still experimental. For now, the best approach is likely to not rely on a media query at all.

5. Browser testing

Edge, Internet Explorer, Firefox, and Chrome all support Windows High Contrast Mode, but not equally. Edge and Internet Explorer both support the -ms-high-contrast media query, and both will correctly map colors to user-set (or default) system colors. Firefox will adopt high contrast mode styles, but not fully respect system colors. Chrome does not adopt high contrast mode styles out of the box, but can be made to do so by going to chrome://flags/ and setting "Forced Colors: Enabled".

Based on media query support, correct system color mapping, and probable WHCM user base, Edge seems the best bet for Windows High Contrast Mode testing. As support shifts in the future, that will likely change to include other browsers as well.

Further Reading

All the links below are especially good this week (not that they usually aren't 😄). I'd particularly recommend Melanie's talk; she's done a bunch of work around the standardization of forced-colors, and is largely responsible for me knowing much of anything about high contrast media queries.

• Operating System and Browser Accessibility Display Modes - The A11y Project
• A great all-round HCM explainer - Adrian Roselli
• How to use -ms-high-contrast - Greg Whitworth
• Finessing forced colors (talk) - Melanie Richards
• MS Edge High Contrast explainer

Part of this flood of grid accessibility questions might be caused by a quirk of where I happen to work, but I don't think that's the only reason tables and grids are over-represented in accessibility bugs. The semantics for tables and grids are relatively complex, and can unexpectedly break due to extra <div>s or CSS display values; grids can have some pretty complex keyboard interaction, and good accessibility documentation is scarce; the visual layout does not play well with mobile viewports or high levels of zoom; most out-of-the-box solutions for things like row selection, sorting, filtering, and virtualization break the screen reader experience. Actually, most out-of-the-box grid components out there have pretty poor accessibility across the board -- even the ones that claim otherwise. All of these combine to make it difficult to get tables and grids right.

So, partly for fun and partly in a futile attempt to reduce my daily email load, let's use a series of posts to take a deeper look at some of the ways tables and grids can go wrong:

1. Using a grid when a table is needed, or vice versa
2. Semantics and keyboard navigation
3. Small viewports, zoom, and other visual accessibility issues
4. Sorting and filtering
5. Row selection
6. Virtualization (i.e. loading rows on demand in a very large grid or table)

This first post is going to cover what should be the first question asked when creating a table or a grid, which is: should I be creating a table or grid?

What is a table, really?

The minimum requirement for both tables and grids is that they contain information whose structure is characterized by a two-dimensional relationship.

Since that's a bit of a mouthful, what I mean is that the information in each cell of a table gains additional context from its relationship to both a row and a column. For example, here are two different ways to present the same information, one of which delivers a two-dimensional relationship, and one does not:

Example 1:

Example 2:

The first example makes it easy for users to skim times and locations by organizing the information as tabular data, and the second example makes it easier to skim event titles by using a simpler list structure with headings. Both are valid choices, depending on what is deemed most important for a user in the context in which the events are displayed.

The important thing is that if a design decision is made to structure information as a table to surface column and row relationships, then it needs to be semantically marked up as a table to provide that same experience to screen reader users.

Here's another example of a good use of a table; in this case, the information would not be nearly as understandable in a list:

I've actually used tables on this blog previously to display browser and screen reader support information in the Playing with State article (this table has both column and row headers):

So, in essence: a table is a method of displaying information to enable the easy consumption of two-dimensional relationships within that information.

What is a Grid?

All of the requirements around two-dimensional information structure that apply to a table also apply to a grid, but with the addition of interactivity. Visually, tables and grids can look the same or very similar, and both should support consuming information in the same way.

Grids differ from tables in how they support interactivity: all cells are focusable and keyboard navigable, and the general idea is that many if not all of the cells will support some type of user action.

Possible user actions within a grid could include editing a cell value (common in a spreadsheet), selecting or deselecting a cell, and reordering, inserting, and deleting rows or columns. If most of the cells are not interactive, then it seems likely that a table would be a better choice than a grid.

Grids should also be a single stop in the tab order regardless of how many interactive elements they contain, since keyboard navigation is handled by the author by listening to arrow keys, home, end, page up, page down, etc. For that reason, keyboard navigation within a grid can be much more efficient than tabbing between focusable elements within a table.

These semantic and interaction differences between a table pattern and a grid pattern are only really relevant to keyboard and screen reader users; there is no meaningful change in visuals or pointer interaction when switching from one to the other.

An editable spreadsheet is a very straightforward use case for a grid. Sort of like an Excel-lite, like this spreadsheet for entering expenses:

The following example of a grid for managing virtual machines doesn't involve editing cell values, but does provide multiple actions per row:

There are even some pretty creative uses you can put to a grid, such as an online board game like bingo or chess. Cordelia McGee-Tubb explored this in her article about building an accessible bingo web app.

What is not a grid

Back in ye olde days of the web, before CSS flexbox and grid, tables were sometimes used for layout since they had excellent cross-browser support and made complex layouts relatively easy to code. This littered the web (and email inboxes) with semantic <table>s that did not contain tabular data, and created some pretty long-lived headaches for browser and screen reader vendors.

Luckily, those days are behind us, and now no developers ever misuse semantic HTML elements or ARIA roles.

coughs. What's that? That's not true? Ah well, guess I still need to finish this article and go to work tomorrow.

So what does misusing a grid look like in modern web development, now that layout tables are passé? Generally the not-grid grids I come across fall into two general categories:

1. It's not all that interactive, and should probably be a table
2. It's highly interactive, but not tabular data. It should be something else entirely.

Sometimes there seems to be the misconception that if a table has any interactivity, it must be a grid. Tables can be sortable, filterable, virtualized, and can contain links and buttons without needing to be a grid. We'll go a bit more into how to choose a table vs. a grid in the next section, but for now, remember: tables can be your friend too.

Highly interactive sets of items that do not have meaningful row and column relationships are also not grids. This is still true even if they are visually laid out in rows and columns, if those rows and columns do not provide meaning. A good example is this interface that allows users to pick from a list of apps: it is visually laid out in a grid pattern, but is not semantically a grid.

Then there's the unfortunate wording and example in the ARIA Authoring Practices about "layout grids" that seems to support this misuse. I'm not going to go into it because Adrian Roselli has already written an article about it, provocatively called ARIA Grid as an Anti-Pattern. Suffice it to say that the rationale seems pretty similar to the layout tables of yore: it identifies a pattern that is difficult to implement with the tools we have today, and then decides the best solution is to pretend that pattern is actually a table (or grid) (spoilers: it is not).

OK, now that I've burned that bridge, let's move on to the fun part --

When do you use a grid vs. a table, and why?

The examples above were all pretty straightforward: a data table with no interactive children should pretty clearly be a table, and an editable spreadsheet absolutely needs to be a grid. There's a fair amount of grey area in between, though. For example, before reading any further ask yourself whether you'd choose a table or a grid for each of these examples:

1. A table of data primarily for reading, but each row has a few actions, e.g. view details / delete
2. A table that is primarily static content, but with multiple links per row, and over 50 rows
3. A table whose primary purpose is to select rows, but has otherwise static, read-only data

It's a bit of an unfair question, since both table and grid are valid answers to each of those cases, depending on other factors. I like to split those factors into two categories: purpose and context.

Purpose

Earlier, I mentioned that the number of interactive cells might indicate whether a table should be a grid or vice versa. That's not wrong, but there is no magic threshold where because you determine that more than 50% of cells are interactive, it must be a grid. Instead, I like to think about whether the primary purpose of the UI control is:

Reading:
If the primary purpose is for the user to consume and understand tabular information, then it leans towards being a table. This is true even if it contains many links or buttons.

Interacting:
If the primary purpose is to provide an interface for the user to edit, manipulate, or otherwise interact with the content it presents, then it leans towards being a grid. Even if most of the cells are static content.

Using this metric, the first two theoretical examples above (the data table with view/delete buttons, and the large table with multiple links) would lean towards being implemented as tables, and the third example (where the user is expected to select rows of static data) would lean towards being a grid.

Basing table vs. grid roles on primary purpose is more than just being pedantic about semantics. If a control is primarily intended to enable a user action or set of actions, it's more likely that a user will spend most of their time moving between and interacting with controls within the grid. In that case, efficiency in moving keyboard focus has a high priority.

If the primary purpose is consuming information, then a user is less likely to need to shift keyboard focus frequently, and simplicity and discoverability matter more than keyboard efficiency.

Context

Table and grid controls don't exist in a vacuum (unless you get so fed up you chuck your computer into space). The surrounding UI, the type of interface you're building, and the ecosystem it lives in will all contribute to user expectations.

For example, if you're building an admin interface for managing a store, you may find your app contains many highly interactive grids (inventory, employee management, finances, etc.). Then imagine a single view within that app contains a grid that is perhaps less interactive -- let's imagine a table of user accounts, each with a single "Edit" button.

Even if that example seems like a good fit for a table role when considered on its own, in context there's a strong case for using a grid to preserve consistency and predictability across the entire app.

Surrounding context is still important if the table or grid in question is the only control of its type. If the context is more like an app than a website in that it is highly interactive and uses other composite widgets like menus, tabs, and trees, then a grid is less likely to confuse a user. On the other hand, a lone grid on a typical restaurant website is much more likely to surprise and confuse people.

Use of a javascript framework like React or Angular, or client-side routing are not good indicators of app vs. website. Much like table vs. grid, web app vs. web site is all about whether the primary purpose is consuming static content, or enabling rich user interaction.

Another piece of context to examine is how long and how frequently your average user expects to interact with your interface. The more time an average user spends using a particular interface, the more they are likely to care about how quickly they can navigate it.

Grids have a steeper learning curve than tables and more support quirks across assistive tech, but they can also be significantly more efficient once learned (if built well). Table semantics have very robust support across screen readers and just about everyone knows how to mash the tab key, but a large table with many tab stops can really slow down keyboard-only navigation within it.

A web app for managing store data like the one imagined earlier would likely have users who visit daily, perhaps for years. Requiring users to spend some time learning how to use grids, trees, tabs, menus, and custom keyboard shortcuts is a reasonable choice in exchange for long-term efficiency. In an app like that, any table with a significant number of interactive elements could lean towards becoming a grid.

No one expects a rogue grid on your public-facing store website, though. Maybe make that a table, even if it has a lot of interactive children.

Also of note: just because Gmail, Excel Online, or an online tax software (to pick a random example that has nothing to do with my weekend plans) chooses to use a grid (or menu, tree, etc.), it does not mean the same choice makes sense elsewhere.

Conclusion

Tables and grids just want to be your friends, so long as you approach them for the right reasons.

Consider a table when:

• Displaying tabular data
• The primary purpose is for the user to read that data
• Discoverability and a low barrier to entry are more important than efficiency
• There are not too many interactive children, or the context is primarily other static content

Consider a grid when:

• Displaying tabular data
• The primary purpose is to enable user interaction
• Efficiency is more important than a low barrier to entry
• There are many interactive children, and the context is primarily interactive and app-like

And that's it on tables vs. grids! Next up is a more technical look at semantics and keyboard interaction within interactive grids.

Further reading

• Grid description in the APG (beware the "layout grid")
• Building an accessible bingo web app - Cordelia McGee-Tubb
• Hey, It’s Still OK to Use Tables and ARIA Grid As an Anti-Pattern - Adrian Roselli

In the first post of this grids series, I wrote that the defining feature of grids and tables is that they present two-dimensional relationships in a set of data. Or, put another way, they are designed to make it easy to skim both row and column relationships.

Row and column relationships are handled visually by lining up each cell horizontally with other cells in the same row, and vertically with other cells in the same column.

Screen readers present the same relationships non-visually with a number of different UX features that can vary by screen reader. These generally include:

• providing custom shortcuts to navigate by column or by row
• reading row- and column-header information when changing rows or columns
• reading row index and column index information
• providing a custom shortcut to read row- or column-headers on demand

Table and grid semantics boil down to creating a programmatic definition of row and column relationships. Screen readers are able to provide their table and grid experience only if the software can parse the row and column relationships that are conveyed visually.

Once more for emphasis:

Screen readers are able to provide their table and grid experience only if the software can parse the row and column relationships that are conveyed visually.

If a developer were to code a collection of plain <div>s to visually look like a table, the resulting non-visual experience would be a bit like if someone had Dali paint a grid, then gave that painting to you and told you that your job depended on you being able to read it.

Structural table and grid semantics

The foundation of table semantics is creating a relationship between cells in the same row, and between cells in the same column. This can only be done with good HTML structure.

In order for a visual row of cells to also behave like a row for screen readers, those cells must all be children of the same row. And in order for a visual column of cells to also behave like a column, they must all have the same child index within their parent row.

Sometimes legacy code or some outside requirement means that you end up working with a less-than-perfect DOM structure. Maybe you’re stuck using <div>s, and there happen to be too many of them. That particular problem -- too many extra elements -- can be fixed, but out-of-order cells or incorrect groupings can only be fixed by re-ordering the HTML.

ARIA can help prune extra non-table nodes from the accessibility tree and it can change what a screen reader says when it encounters a specific cell, but only the structure of the HTML itself can enable necessary screen reader interactions and shortcuts within a table.

Practical Example 1: non-table nodes

Here is some sample table code that includes both extra non-table elements and checkboxes outside of grid cells that illustrates what I’m talking about. This particular example uses ARIA semantics rather than <table> elements to demonstrate the effect of improper table structure. Don't worry too much about the specific roles right now; we'll cover those later.

<div role="table" aria-label="Animals at the Seattle Aquarium">
  <div role="row">
    <input type="checkbox" class="row-selection" aria-label="select all rows">
    <div role="columnheader">Animal type</div>
    <div role="columnheader">Number</div>
  </div>
  <div role="row">
    <input type="checkbox" class="row-selection" aria-label="select sea otter row">
    <section class="animal-cell">
      <div role="cell">Sea Otter</div>
    </section>
    <div role="cell">3</div>
  </div>
  <div role="row">
    <input type="checkbox" class="row-selection" aria-label="select river otter row">
    <section class="animal-cell">
      <div role="cell">River Otter</div>
    </section>
    <div role="cell">2</div>
  </div>
  <div role="row">
    <input type="checkbox" class="row-selection" aria-label="select harbor seal row">
    <section class="animal-cell">
      <div role="cell">Harbor Seal</div>
    </section>
    <div role="cell">3</div>
  </div>
</div>

If you run NVDA on this table markup in Firefox, it chokes in two separate ways:

1. on the checkbox that exists outside of a cell
2. on the extra <section> elements.

See if you can catch both problems in this video, or by directly testing the examples page.

Different browsers do different amounts of error correction for authoring errors in table markup, so trying this same markup in a different browser and screen reader pairing may get you different results. If a table works fine in one screen reader but fails in another, it might be a screen reader or browser bug, but it might also be a problem with the markup.

The best way to ensure every screen reader’s table UX works properly is to construct a clean accessibility tree. I wrote about using role="presentation" or role="none" to fix the accessibility tree of composite widgets like tables and grids in a previous blog post, Roles and Relationships.

Right now, the accessibility tree for that table code looks like this:

If we apply role="presentation" to all the <section> elements, we end up with this accessibility tree:

There's still one problem: the checkboxes are still not reachable with table navigation, since they're not within a table cell. When creating tables and grids, all content must be contained within the cells. To fix that, we need to wrap the checkbox in an element with role="cell":

<div role="table" aria-label="Animals at the Seattle Aquarium">
  <div role="row">
    <div role="columnheader">
      <input type="checkbox" class="row-selection" aria-label="select all rows">
    </div>
    <div role="columnheader">Animal type</div>
    <div role="columnheader">Number</div>
  </div>
  <div role="row">
    <div role="cell">
      <input type="checkbox" class="row-selection" aria-label="select sea otter row">
    </div>
    <section class="animal-cell" role="presentation">
      <div role="cell">Sea Otter</div>
    </section>
    <div role="cell">3</div>
  </div>
  <div role="row">
    <div role="cell">
      <input type="checkbox" class="row-selection" aria-label="select river otter row">
    </div>
    <section class="animal-cell" role="presentation">
      <div role="cell">River Otter</div>
    </section>
    <div role="cell">2</div>
  </div>
  <div role="row">
    <div role="cell">
      <input type="checkbox" class="row-selection" aria-label="select harbor seal row">
    </div>
    <section class="animal-cell" role="presentation">
      <div role="cell">Harbor Seal</div>
    </section>
    <div role="cell">3</div>
  </div>
</div>

And that's all that's needed to fix the table's accessibility tree so that screen readers can navigate through rows and columns, and properly associate cells with their column headers.

ARIA table and grid roles

Tables

The previous example showed the role hierarchy needed to build a table with ARIA. There are roughly two reasons you might need to use ARIA roles to construct a semantic table:

1. For whatever reason, you cannot use HTML <table> elements
2. You use HTML table elements, but you need to override the table's CSS display property.

In both cases, you would need to explicitly declare table semantics with ARIA for them to be recognized by screen readers.

The available ARIA roles for tables are these:

• table: the top-level container role, equivalent to the <table> element
  • rowgroup (optional): can denote a related group of rows, equivalent to the <thead> and <tbody> elements
    • row: groups cells into rows, equivalent to the <tr> element
      • columnheader: used to create a header cell that labels all body cells within the same column, equivalent to <th scope="col">
      • rowheader: used to create a header cell that labels all cells within the same row, equivalent to <th scope="row">
      • cell: all table content must be in one of these, equivalent to the <td> element

If you use semantic HTML table elements and do not override the CSS display property of any of them, then you do not need to use any ARIA roles.

Grids

Grid semantics differ slightly from table semantics, and always need to be explicitly declared. I went over why you might want grid semantics vs. table semantics in the first post in the grid series. Assuming you do, in fact, need a grid, these are the available ARIA roles:

• grid: the top-level container role
  • rowgroup (optional): can denote a related group of rows, equivalent to the <thead> and <tbody> elements
    • row: groups cells into rows, equivalent to the <tr> element
      • columnheader: used to create a header cell that labels all body cells within the same column, equivalent to <th scope="col">
      • rowheader: used to create a header cell that labels all cells within the same row, equivalent to <th scope="row">
      • gridcell: all grid content must be in one of these, equivalent to a <td> within a grid

You may already have noticed that these are identical to the ARIA table roles, with the exception of grid and gridcell.

The easiest way to create a grid is to use HTML table elements, and add role="grid" to the top-level <table>. No other roles are needed if the table is otherwise semantically correct and the CSS display properties are not overridden.

If that is not the case, all other roles must also be explicitly declared, just as with table semantics. Using rowgroup is optional for both tables and grids, and can be used to group header rows vs. body rows. It can also be used to group related rows within the table or grid body.

A quick note on CSS display properties

Despite their names, the CSS display: table and display: grid styles are not related to ARIA table and grid semantics, and do not (or should not) create table and grid nodes in the accessibility tree.

I've also mentioned above that overriding the default CSS display of table elements (including <tr> and <td> elements) will remove their default semantics. Adrian Roselli's CSS display properties vs. HTML semantics and Steve Faulkner's Short note on what CSS display properties do to table semantics include more specifics on how that happens. The TL:DR; is if you do this, you need to use all the ARIA table or grid roles instead of relying on HTML to handle screen reader accessibility by default.

Supplementary table and grid semantics

Lazy-loading rows or columns

There are four ARIA attributes available for both tables and grids that can be extremely useful if you are lazy-loading rows in a very large table or grid. For example, you could have a table that contains 500 rows total, but you only render 25 in the DOM at any given time to improve performance. If you do this without using ARIA, a screen reader will always announce the rendered rows as 1-25 out of 25, even if the user is really on rows 150-175 out of 500.

To fix this, you can use these two properties:

• aria-rowcount="500" on the <table> or role="table/grid" element
• aria-rowindex on each <tr> or role="row" element.

If you lazy-load columns as well as rows, you can use these properties as well:

• aria-colcount on the <table> or role="table/grid" element
• aria-colindex on each <td> or role="cell/gridcell" element

None of these attributes are necessary if all the rows and columns are present in the DOM at all times. They also are not necessary if your grid has multiple pages, but does not dynamically load content by scrolling.

Practical example 2: out-of-order rows

It is possible to use CSS to style elements to visually appear in a different order than they are defined in the DOM. You can brute-force this with position: absolute;, or use reordering options that come with display: grid; and display: flex;.

Screen readers do not follow the visual order, and will always rely on DOM order, which translates to the order in the accessibility tree. This holds true for tables and grids, despite the aria-rowindex and aria-colindex properties.

To illustrate, let's add some aria-rowindex and aria-rowcount properties to the table from earlier, and style so the visual order matches the declared aria-rowindex order. Here is the HTML:

<div role="table" aria-label="Animals at the Seattle Aquarium" aria-rowcount="100">
  <div role="row" aria-rowindex="5">
    <div role="columnheader">
      <input type="checkbox" class="row-selection" aria-label="select all rows">
    </div>
    <div role="columnheader">Animal type</div>
    <div role="columnheader">Number</div>
  </div>
  <div role="row" aria-rowindex="7">
    <div role="cell">
      <input type="checkbox" class="row-selection" aria-label="select sea otter row">
    </div>
    <div role="cell">River Otter</div>
    <div role="cell">2</div>
  </div>
  <div role="row" aria-rowindex="6">
    <div role="cell">
      <input type="checkbox" class="row-selection" aria-label="select river otter row">
    </div>
    <div role="cell">Sea Otter</div>
    <div role="cell">3</div>
  </div>
  <div role="row" aria-rowindex="8">
    <div role="cell">
      <input type="checkbox" class="row-selection" aria-label="select harbor seal row">
    </div>
    <div role="cell">Harbor Seal</div>
    <div role="cell">3</div>
  </div>
</div>

And here is how NVDA treats it:

The most important takeaway here is the aria-rowcount, aria-rowindex, aria-colcount, and aria-colindex properties will affect what a screen reader says when encountering a specific element, but will not change any other behavior or navigation. This is also generally true of most ARIA states and properties.

I realize this example may seem fairly contrived, but there is at least one major grid library out there that handles lazy-loading by re-using and visually re-ordering the DOM elements used for rows as the user scrolls through the grid. The result is the visual order does not match the DOM order, and the screen reader accessibility is entirely broken.

Accessible lazy-loaded content takes more than just these four ARIA properties, which is why there will be an entire article about on-demand grids later, hopefully!

Complex headers

Sometimes column headers and row headers span multiple columns or rows, such as in this table:

If you are using table elements, the colspan and rowspan attributes have you covered. These work even if you are using ARIA to re-assert role="columnheader" or role="rowheader".

If, however, you are using <div>s or other non-table elements, the aria-colspan and aria-rowspan correspond directly to the colspan and rowspan attributes.

Miscellaneous other table and grid ARIA

We've covered all the table- and grid-specific ARIA attributes, but there are some others you might find useful, perhaps along with a good overview of ARIA labels and descriptions:

• aria-label or aria-labelledby on the table or grid element: these corresond to using the <caption> element in an HTML <table>, and are a good idea to use to name the table or grid, particularly if there is more than one table or grid in the page.
• aria-describedby on the table or grid element: if you want to associate a longer supplementary description in addition to the name
• aria-label or aria-labelledby on the rowgroup element: if you have multiple rowgroups in the table body, adding a name to each is a good idea
• aria-activedescendant on the grid element (not on tables): we'll go over this in the next article on keyboard interaction

There are other supported attributes that I'm not going to cover that are purely use-at-your-own risk, like aria-selected on gridcells. Only use those if you're really sure you know what you're doing.

If you've made a habit of reading the supported attributes table in the ARIA spec, you may have noticed that rows support the following attributes:

• aria-expanded
• aria-level
• aria-posinset
• aria-setsize

These are a bit of a gotcha "supported" status in the ARIA spec, since they're only supported on rows within treegrids, and are not supported in either grids or tables. For more on treegrids, see the next section.

Treegrids

Not today, Satan.

Wrap-up and further reading

Table and grid semantics are... not simple, clearly. The regular old been-around-the-block <table>, <tr>, and <td> elements do a lot of heavy lifting under the hood. There could easily be another article's worth of information on how all of this translates to accessibility APIs, if one wanted to really get in the weeds.

I used the NVDA screen reader for the recorded demos, but all Windows screen readers have very similar table interactions (they even all use Ctrl + Alt + arrow keys). VoiceOver on macOS uses different keyboard interactions, but also presents row and column information. You can try out the demos (plus a few other examples) with a screen reader of your choice on the grid semantics demo page.

This article and the previous one have focused about equally on both tables and grids. The next article on keyboard interaction will focus solely on grids, and hopefully be finished a bit faster than this article's 6-month time frame.

Finally, more eloquent people have already written about table semantics in different and helpful ways. Here are some of those articles:

• Data table design pattern - Heydon Pickering
• A practical example of fixing a broken table with ARIA - Steve Faulkner
• Tables, CSS Display Properties, and ARIA - Adrian Roselli (he also has other worthwhile articles related to table semantics on his site)
• A practical example of creating a semantic table in SVG - Léonie Watson

Disclaimer: although I made an account years ago, I never used it until now. I'm not interested in convincing anyone to use Mastodon, or to leave Twitter. Do what works for you, in this hellscape of the 2020s.

Getting started

I will do my best to fully describe the steps with semantic accuracy for anyone using a screen reader, or anyone struggling with some of the contrast issues present on the site. If you run into any specific issues creating an account that are not covered here and want to share info, DM me.

Step 1: Pick a server

This can sound daunting, since there are so many options. Don't overthink it -- you can move your account later without losing followers. You can also follow anyone on any server, and search for people across all servers.

Here are four options, primarily geared towards folks in the web accessibility or disability communities:

1. A big general server like mastodon.social or mas.to: these are large enough and old enough to be reliable. The drawback is they're so large that the server-specific "Local" feed isn't going to be helpful.
2. toot.cafe: a number of web and accessibility people are on here. Slightly smaller, and as of writing is not accepting new users (though that may easily change, it's a weird time right now).
3. a11y.info: a very small server with almost exclusively web accessibility folks. Run by Michael Spellacy.
4. dragonscave.space: another very small server, run by a blind admin (Talon). Lots of blind folks and accessibility experts on here. If you're looking for advice on using Mastodon with a screen reader, there are almost certainly people who can help on this instance.

If you're not happy with those, you can browse a list of servers on joinmastodon.org or, I dunno, ask someone else for recommendations.

Step 2: Sign up

If you're already using an app, you can probably sign up through there. If not, go to the /about path of the server you've picked, or use one of the following links for the servers I listed earlier:

• mastodon.social signup (not accepting new users as of writing)
• mas.to signup
• toot.cafe signup (not accepting new users as of writing)
• a11y.info signup
• dragonscave.space signup

When you do this on a server accepting new users, you will encounter one of a two things:

1. A page with a heading for the name of the server, immediately followed by a form with four fields and a checkbox.

The fields are:

• Username
• Email address
• Password
• Confirm password
• A checkbox to confirm that you agree to server rules and terms of service (the exact wording can vary by server)

Some servers may have additional custom fields. There is a large button with the text like "Sign up" or "Request an invite" immediately following the checkbox.

Warning for people using screen readers: when a server is not accepting new users, the fields in the sign up form are not disabled. Before you begin filling out the form, verify that the submit button has a label like "sign up" or request an invite", and not "X server is not accepting new members".

2. Some servers ask you to agree to terms and conditions before signing up. For these servers, you might not reach the form directly. Look for a "Create account" link. It is in different places on desktop vs. mobile:

After agreeing to any server-specific terms, you should reach the same form described earlier.

Step 3: Email confirmation

After submitting the form, you should receive an email with a title like "Mastodon: Confirmation instructions for [server name]".

Follow the "Verify email address" link, and you should get to your new profile.

Step 4: You have an account, and can follow people!

You can use the very low-contrast search field to find people across all of Mastodon (not just your server) It's at the top of the left sidebar on desktop, or under an magnifying glass icon button labelled "Search" on mobile.

Here's a list of web a11y people I think are worth following to start out (not comprehensive, I haven't been here long myself and I'll probably keep adding to it, if I remember). Eric Eggert has a longer and better-curated list in his very good article on accessibility in the fediverse.

In no particular order:

• Me! I'm here :) @codingchaos@vis.social
• Frank Elavsky @frankelavsky@vis.social
• Léonie Watson @tink@front-end.social
• Scott O'Hara @scottohara@mastodon.social
• Adrian Roselli @aardrian@toot.cafe
• Eric Bailey @ericwbailey@front-end.social
• Sam Kapila @samkap@front-end.social
• Sara Soueidan @SaraSoueidan@front-end.social
• Alice Boxhall @sundress@mastodon.social
• Eric Wright @ewaccess@mastodon.social
• Eric Eggert @yatil@micro.yatil.net
• Chancey Fleet @ChanceyFleet@mas.to
• Doug Schepers @shepazu@mastodon.social
• Crystal Preston-Watson @ScopicEngineer@mstdn.social

Step 5 (optional): Find an app

There is an official Mastodon app available for Apple and Android, with links to both in the JoinMastodon apps page. There is also a list of alternative apps further down the same page, under the "Browse third-party apps" header.

I have no personal recommendations, but have anecdotally heard good things about Toot! (paid), and that some blind folks have been able to use Tweesecake on Windows and macOS.

If I find out more info, especially on clients with good contrast, distraction-related settings, and animation prevention, I'll update here.

Coda: some resources

• Fedi.tips: an unofficial and non-technical guide to using Mastodon. Has some really good tips, and some basic accessibility info.
• Eric Eggert's Mastodon a11y post: includes a long list of web accessibility people to follow
• A screen reader guide to Mastodon: note -- this may have some info that is out of date, at least regarding the web interface.
• How Mastodon search works -- also goes into why it works the way it does, despite seeming unclear when coming from Twitter
• There are some good tips in this twitter thread from Lainey Feingold, and the original tweet from Haben Girma

That's it! I'll probably keep my account on twitter till the bitter end, but I hope the wonderful people who have stitched together a community on the bluebird hellsite will still have a place to gather in the coming years, on Mastodon or elsewhere.

This is an attribute that is entirely concerned with screen reader accessibility. Specifically, it allows certain scoped exceptions to the screen reader behavior of only enabling interaction with a single element at a time.

Even more specifically, you probably want to start reaching for aria-activedescendant whenever you want to provide a user with immediately relevant actions, autocomplete suggestions, or matching options while they are typing text.

For example: if the user's keyboard focus is on a text input, their screen reader will normally only pass along information and updates about that one text input. Any changes happening elsewhere on the page will not be communicated, with two notable exceptions:

1. Live regions. I'm not going to elaborate on these here, but I have talked about them before.
2. If the focused element has an aria-activedescendant attribute: changes to the element referenced by that attribute, or changing which element is referenced by aria-activedescendant.

Diving more into the text input example, aria-activedescendant makes it possible to have screen readers expose both changes to the text input (e.g. the value, valid/invalid state, expand/collapse state, etc.) and also changes to one other associated element, usually in a popup. In other words, it is the primary mechanism that makes comboboxes work:

Sometimes this causes people to think of the active descendant as a second focus, or talk about the associated aria-activedescendant element as "focused".

While keyboard focus and aria-activedescendant are quite similar -- maybe even more similar than you might think -- they are still distinct in a number of ways that are important for web developers to be able to identify.

What is focus?

This is the easy one, and most developers are probably already familiar with it. A document may have exactly one focused element at a time, and that element can be queried using the document.activeElement DOM attribute.

The focused element of the active document will be the target of any keyboard events, which makes it particularly important when creating custom keyboard interactions.

A screen reader cursor is not the same as keyboard focus, although screen readers will also usually have their cursor follow any changes in the focused element. Those changes can occur either through user interaction (e.g. tabbing) or programmatic focus changes (e.g. calling element.focus() to move focus back to the triggering button when closing a dialog). However, certain screen readers will sometimes ignore programmatic focus changes in favor of their own internal heuristics about where the screen reader cursor should go (side-eye at VoiceOver intensifies).

Identifying the currently focused element can get a little more tricky in the case of multiple documents in nested iframes, or custom web components with shadow roots.

For example, if focus enters a button within an iframe, querying the top-level document's activeElement will return the iframe and not the focused element within it. Similarly, if focus is within the shadow root of a web component, document.activeElement will return the web component's host node. You would then need to query the iframe's document.activeElement, or host node's shadowRoot.activeElement to find the specific element that has focus.

There are of course other nuances to tracking focus changes that also have the potential to cause premature hair loss in developers:

• If document.activeElement is queried in a blur event handler, it will return document.body.
• Pressing the tab key does not always move focus starting from document.activeElement. There are times when the sequential focus navigation starting point diverges from the currently focused element.
• When navigating the web using a keyboard paired with an iOS device, the web page receives focus events, but no keyboard or pointer events. Someday I will write 5000 words about the focus-handling implications for this and it will never be published because of all the swearing.
• Some other weird edge case that I either can't remember or blissfully have yet to encounter.

As with many things, focus is simple right up until it isn't.

What is an active descendant?

It's the element identified by aria-activedescendant, of course.

There's actually the smallest hint of something useful in that tautology, which is that an active descendant on the web only exists with the help of ARIA; there is no way to create one using only HTML or Javascript (apart from literally using JS to set element.ariaActiveDescendant).

This means that we can look at the ARIA spec to tell us the allowed uses and limitations of aria-activedescendant -- what roles it can be used in, authoring requirements, and other limitations.

Distilling the information in the spec, there are two patterns that support aria-activedescendant:

1. Patterns similar to a combobox, where focus remains on an editable region to enable typing while aria-activedescendant points to a related item, often an option in a popup listbox:

2. Composite widgets like tree or grid can accept focus on their parent node, and have aria-activedescendant point to child treeitem or gridcell elements instead of managing focus between those child elements directly.

I still have no idea why someone would choose to use aria-activedescendant for #2 in practice, but the important thing is that you can, I guess.

How to use aria-activedescendant

The value of aria-activedescendant must point to the id of an element that is either:

1. a descendant of the composite widget that has aria-activedescendant:

<div role="listbox" tabindex="0" aria-activedescendant="opt2">
  <div role="option" id="opt1">Otter</div>
  <!-- this is a descendant of the listbox, so it is OK -->
  <div role="option" id="opt2">Opossum</div>
  <div role="option" id="opt3">Ocelot</div>
</div>

2. a descendant of a composite widget that is ponted to via aria-controls on a combobox, textbox, or searchbox with aria-activedescendant:

<input type="text" aria-controls="listbox" aria-activedescendant="opt2">
<div role="listbox" id="listbox">
  <div role="option" id="opt1">Otter</div>
  <!-- this is a descendant of the listbox, which is pointed to by aria-controls, so it is OK -->
  <div role="option" id="opt2">Opossum</div>
  <div role="option" id="opt3">Ocelot</div>
</div>

The value of aria-activedescendant should not point to some random element on the page, even when it is defined on a role that supports it:

<!-- DON'T DO THIS -->
<input type="text" aria-activedescendant="button">
<!-- this is a random button, what is even going on here -->
<button id="button">nope</button>

How does aria-activedescendant work?

Knowing that aria-activedescendant is an ARIA construct is helpful in one additional way: we can look at the Core AAM spec (the accessibility API mapping spec for ARIA) to determine what is going on under the hood.

Since aria-activedescendant exists for the benefit of screen reader users, and accessibility APIs mediate most of the DOM-to-screen reader translation, looking at the API mapping can tell us a lot about the intended functionality of aria-activedescendant.

One small side note -- while aria-activedescendant is specifically for screen reader users, this is not true of all ARIA attributes, and also not true for all accessibility API mappings.

The mappings:

...

So, uh, about that second focus thing...

Why use focus vs. aria-activedescendant

The thing about ARIA is that it does not affect browser behavior or functionality -- only semantics and accessibility API mappings. All keyboard events will still fire on the true focused element, and there are no global DOM methods to query the currently relevant active descendant in the manner of document.activeElement. The only context in which the active descendant behaves like a second focus is when it comes to a screen reader's virtual cursor.

Even for screen readers, aria-activedescendant is not entirely the same as a second focus. As an example, let's look at what happens if a Windows screen reader users toggles between browse mode and forms mode after navigating through elements using aria-activedescendant vs. focus:

• With factory settings, NVDA, Narrator, and JAWS all update keyboard focus to follow their virtual cursor when moving over focusable elements. This means that switching between browse mode and forms mode will usually keep you in the same place.
• Using NVDA or Narrator, the element identified through aria-activedescendant will not update to match the screen reader's cursor location. Switching between browse mode and forms mode may cause unintended side effects.
• JAWS is the one Windows screen reader to handle mode switching with aria-activedescendant gracefully.

Syncing the screen reader cursor and page focus is a little more complicated than even this list would imply, but in ways that are not directly relevant here.

Automatic mode switching

One way in which aria-activedescendant is similar to focus is that the role of an active descendant will cause Windows screen readers to switch modes in exactly the same way that the role of a focused element does. For example, if you are using NVDA and are interacting with an input in forms mode, tabbing to a button will switch you to browse mode (unless you've disabled this behavior in user settings). By the same mechanism, if we bring back this cursed code:

<input type="text" aria-activedescendant="button">
<button id="button">nope</button>

Updating aria-activedescendant to point to that button while the input is in focus will also switch the user to browse mode. Subsequent keyboard interactions will thereafter be handled by NVDA instead of by the page, at which point the script updating aria-activedescendant in response to keyboard events will stop doing anything. The user will also no longer be able to type without manually switching back to forms mode. This is the primary reason to avoid having aria-activedescendant point to elements that are not part of a composite widget like options in a listbox.

Mobile screen readers will essentially ignore aria-activedescendant, since they move their cursor through the accessibility tree in response to touch input (simplifying a little here; mobile screen readers also support other types of input). This means that an iOS VoiceOver or Android Talkback user will generally swipe through all the options without the aria-activedescendant value changing at all. In some cases, this might be an issue for scrolling if items are also not focusable. If items are focusable, they will generally gain focus when the VoiceOver or Talkback cursor lands on them, natively triggering scroll when needed.

Also VoiceOver on Safari on macOS will ignore aria-activedescendant if you so much as look at it funny.

When to use aria-activedescendant

Comboboxes.

OK but really -- I have not found a real-world use case for aria-activedescendant that does not also involve editing text.

Even in complex use cases of giant virtualized trees, data tables, tree grids, and SVG charts and graphs, managing keyboard focus ends up being simpler to implement and more robust. If anyone has a good example for needing aria-activedescendant outside of a combobox/editing scenario, I'd love to hear about it. I'm sure it exists in theory out there somewhere, presumably right next to a perfectly accessible combobox full of tooltips.

There are a few text editing use cases for aria-activedescendant beyond just comboboxes, however. Some examples include:

• Freeform search inputs that expand a popup of suggestions. I'd generally recommend against putting a role=combobox on a site-wide search for two reasons: comboboxes generally do not imply freeform input, and using that role might make the searchbox harder to find for screen reader users explicitly looking for edit boxes.
• @-mentions inside a chat input. This usually involves a floating listbox or menu anchored to your text insertion cursor. Focus remains in the chat input to enable continued typing, and aria-activedescendant makes the popup accessible. The entire pattern is very similar to a combobox, but without the combobox role.
• Any floating suggestions in a document canvas editing experience (not sure what to call this exactly). Think Google Docs, Word Online, website creation canvases, etc. You might have something like a spelling or grammar suggestions popup appear without pulling the user's focus away from where they currently are in the document.

Generally the theme is to consider aria-activedescendant in any use case where you need to present some immediately relevant supplemental actions related to user input.

Where to use aria-activedescendant

The aria-activedescendant attribute must be defined directly on the element that has keyboard focus for the active descendant to be picked up by screen readers.

I know this was already covered in an earlier section, but I wasn't sure how else to shoehorn in a section on "Where".

Who is aria-activedescendant

Truly we are all aria-activedescendant, at least in our hearts.

I'm not sure where I was going with this. I think this article might be losing focus.

Many thanks and apologies to Eric Bailey and Adrian Roselli for being kind enough to review this article ages ago when I first wrote it.

There are two exceptions that cause non-trivial issues to arise:

1. SVGs (written about more in Eric Bailey's article)
2. Sprinkling forced-color-adjust: none throughout a codebase like cloves in biryani. They may sometimes be helpful, but stumbling across one unexpectedly can make you gag.

This post is aimed at anyone working in an environment with multiple other developers or development teams while needing to maintain a codebase over time. If: you lovingly handcraft all your styles, and everyone who contributes is familiar with all CSS in the codebase, and this stays true both now and in perpetuity, then this probably won't be a problem.

However if you, like me, work in a large and chaotic system where code you write is copied, consumed, customized, and maintained away from your control by many other people, then it is a matter of when and not if a forced-color-adjust: none style will cause high contrast mode bugs.

The problem

By default, forced color modes work by converting UI from author-defined colors into a reduced palette of system colors based on HTML semantics, not authored CSS. Static text will adopt a CanvasText color against a Canvas background. Buttons will use ButtonText on ButtonFace, and disabled controls will have content and borders appear as GrayText.

Even though this is how it works by default, it is still possible to override the default styles and customize forced color styles for both good and evil. There are a few ways to go about this:

1. Intentionally create transparent borders or outlines, knowing they'll only show up in forced colors mode. (This and some other tips are covered in my Quick Tips for High Contrast Mode article)

2. Using a forced colors mode media query, tweak styles using system color keywords:

@media (forced-colors: active) {
  .primary-button {
    border-color: Highlight;
  }
}

(note this only works with system color keywords, other colors will not be rendered without forced-color-adjust: none)

3. Use a forced colors mode media query with forced-color-adjust: none to completely control colors, ideally still using system colors:

@media (forced-colors: active) {
  button[aria-pressed=true] {
    forced-color-adjust: none;
    background-color: Highlight;
    color: HighlightText;
  }
}

So the question you, a savvy reader, may already be asking is: if system color keywords work without needing forced-color-adjust: none, then why include it in that third example?

The reason is because of an unspec'd (unspecced? unspec'èd?) browser behavior: text backplates. In what appears to be a well-intended attempt to save authors from themselves, browsers render a solid-colored backplate to any text over a styled background (this happens with backgrounds on the same element or on ancestor elements). The color of this backplate is Canvas, regardless of the text color.

So if you want to have, for example, a toggle button that inverts colors when pressed, you might start with this CSS:

@media (forced-colors: active) {
  button[aria-pressed=true] {
    background-color: Highlight;
    color: HighlightText;
  }
}

And you would end up with this:

That cursed second button says "A pressed toggle button" for those of you who do not have perfect vision and did not press your eyeball against the screen.

Adding a backplate does make sense and provide a safeguard for readability in some situations: text over images, for example:

However, adding a Canvas backplate for text that has an explicit (system) color style is risky at best, even more so when an explicit (system) background color was also provided. The use of system color keywords presumably in a forced-colors media query already implies a certain amount of intentionality from the author, so dealing with a text backplate often feels like fighting with the browser over who can deliver better colors to the user.

Additionally, the backplate is fully outside web authors' control, and the only thing we can do to fix it is add forced-color-adjust: none:

And then weep.

Wait, why are we crying?

The problem with adding forced-color-adjust: none is that it allows all CSS-styled colors to come through on that element, not just system colors. So even if you (a responsible developer who cares enough about accessibility to have stumbled on this blog) craft beautifully accessible forced-colors CSS using only system color keywords, someone else may come along and unintentionally screw it up. Usually without ever knowing that they affected high contrast mode styles at all.

It looks a bit like this:

Your code: beautiful, lovely, perfect.

@media (forced-colors: active) {
  button[aria-pressed=true] {
    forced-color-adjust: none;
    background-color: Highlight;
    color: HighlightText;
  }
}

Their code: terrible. (But if we're being honest this is perfectly normal and reasonable)

.custom-button[aria-pressed=true] {
  background-color: red;
  color: purple;
}

Since the addition of a .custom-button class creates a higher specificity style, it overrides the original style even though it's outside a forced-colors media query and clearly not intended to affect high contrast mode. And because of the original forced-color-adjust: none, the random red and purple colors come through:

In a collaborative environment, someone somewhere will always take your code and extend or customize it. Often this involves writing styles with a higher specificity selector. Or even a same-specificity selector that comes after your CSS. None of the code involved is unusual or bad practice, which makes it all the worse that it trips up so spectacularly and unpredictably on forced-color-adjust: none.

Individual bugs are fixable, but the downstream CSS author has to manually re-add the forced-color styles back in. Which means the author of that code needs to be aware that this is necessary, even though they themselves never touched or directly overrode forced-colors styles:

.custom-button[aria-pressed=true] {
  background-color: red;
  color: purple;
}

@media (forced-colors: active) {
  .custom-button[aria-pressed=true] {
    background-color: Highlight;
    color: HighlightText;
  }
}

Authors are especially unlikely to realize when they need this, because most of the time they don't. And in practice, web authors should not need to be aware of this level of minutiae when making small style tweaks. If you're the unlucky schmuck maintaining this stuff, good luck trying to keep up-to-date documentation on which specific selectors will need forced-color styles re-asserted every time they are customized.

The library I work on consistently gets a trickle of high contrast questions from partner teams that are caused by variations of this issue. And those are just the ones that get caught. Changing the colors of a shared base control is the most common style customization out there, and every single use of forced-color-adjust: none is one CSS line away from breaking in high contrast.

OK I get it, I just won't use it

So if forced-color-adjust: none is a foot gun, is it possible to avoid it?

No.

Well, I suppose it could be possible for projects that have fairly simple controls and content, but usually no. Here is a reduced list of use cases for overriding colors off the top of my head:

• A primary button style to differentiate the primary action from secondary actions (e.g. for Save / Cancel buttons)
• The pressed state of a toggle button
• The selected date of a datepicker
• Many other selected item styles (tabs, options, rows in a grid, etc.)
• Highlighting the current page in a navigation section

Some of those could potentially use a design that doesn't rely on color at all (e.g. using a check icon to denote selection), but in practice at least sometimes you will need custom high contrast text colors. In theory, putting effort into high contrast styles is a good practice that can improve the user experience quite a bit, making it easier to identify buttons, selected items, and other visual cues at a glance.

In practice, doing so also makes the high contrast UX much more fragile and likely to break over time. And since this is accessibility, the bugs will likely go uncaught for a frustrating length of time as well.

So what should we do?

Cry. Drink. Drunk cry.

But really, it's still probably good to customize high contrast colors when needed, which means you'll need to use forced-color-adjust: none sometimes. Try to keep those instances both infrequent and tightly scoped. Never add forced-color-adjust at a higher level than you need to. And if it's only necessary in one state (e.g. hover or pressed), only add it to that state.

Perhaps someday text backplates will go away (at least for non-image backgrounds) and we can all stop using forced-color-adjust: none entirely. (Except for those weird instances like color pickers where you actually want it. Please don't @ me with your random good use cases, I know they exist.)