Although the interaction is simple, it's an interaction that does not have a consistent native implementation across browsers — despite movement to standardize it. It is therefore a great "hello world" entry point into accessible interaction design using JavaScript and WAI-ARIA.

So why am I talking about it now, after covering more complex components? Because this article will focus on developer and author experience: we're going to make our collapsible regions web components, so they are easy to include as part of larger patterns and in content files.

As we did when approaching tab interfaces, it helps to consider what our component would be in the absence of JavaScript enhancement and why that enhancement actually makes things better. In this case, a collapsible section without JavaScript is simply a section. That is: a subheading introducing some content — prose, media, whatever.

<h2>My section</h2>  
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras efficitur laoreet massa. Nam eu porta dolor. Vestibulum pulvinar lorem et nisl tempor lacinia.</p>  
<p>Cras mi nisl, semper ut gravida sed, vulputate vel mauris. In dignissim aliquet fermentum. Donec arcu nunc, tempor sed nunc id, dapibus ornare dolor.</p>  

One advantage of collapsing the content is that the headings become adjacent elements, giving the user an overview of the content available without having to scroll nearly so much. Expanding the content is choosing to see it.

Another advantage is that keyboard users do not have to step through all of the focusable elements on the page to get to where they want to go: Hidden content is not focusable.

The adapted markup

Just attaching a click handler to the heading for the purposes of expanding the associated content is foolhardy, because it is not an interaction communicated to assistive software or achievable by keyboard. Instead, we need to adapt the markup by providing a standard button element.

<h2><button>My section</button></h2>  
<div>  
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras efficitur laoreet massa. Nam eu porta dolor. Vestibulum pulvinar lorem et nisl tempor lacinia.</p>
  <p>Cras mi nisl, semper ut gravida sed, vulputate vel mauris. In dignissim aliquet fermentum. Donec arcu nunc, tempor sed nunc id, dapibus ornare dolor.</p>
</div>  

(Note: I have wrapped the content in a <div>, in preparation for showing and hiding it using the script to follow.)

The button is provided as a child of the heading. This means that, when a screen reader user focuses the <button>, the button itself is identified but also the presence of its parent: "My section, button, heading level 2" (or similar, depending on the screen reader).

Had we instead converted the heading into a button using ARIA's role="button" we would be overriding the heading semantics. Screen reader users would lose the heading as a structural and navigational cue.

In addition, we would have to custom code all of the browser behaviors <button> gives us for free, such as focus (see tabindex in the example below) and key bindings to actually activate our custom control.

<!-- DON'T do this -->  
<h2 role="button" tabindex="0">My section</h2>  

State

Our component can be in one of two mutually exclusive states: collapsed or expanded. This state can be suggested visually, but also needs to be communicated non-visually. We can do this by applying aria-expanded to the button, initially in the false (collapsed) state. Accordingly, we need to hide the associated <div> — in this case, with hidden.

<h2><button aria-expanded="false">My section</button></h2>  
<div hidden>  
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras efficitur laoreet massa. Nam eu porta dolor. Vestibulum pulvinar lorem et nisl tempor lacinia.</p>
  <p>Cras mi nisl, semper ut gravida sed, vulputate vel mauris. In dignissim aliquet fermentum. Donec arcu nunc, tempor sed nunc id, dapibus ornare dolor.</p>
</div>  

Some make the mistake of placing aria-expanded on the target element rather than the control itself. This is understandable since it is the content that actually switches state. But, if you think about it, this wouldn't be any good: the user would have to find the expanded content — which is only possible if it's actually expanded! — and then look around for an element that might control it. State is, therefore, communicated through the control that one uses to switch it.

Styling the button

We've created a situation wherein we've employed a button, but a button that should look like an enhanced version of the heading it populates. The most efficient way to do this is to eradicate any user agent and author styles for buttons, forcing this button to inherit from its heading parent.

h2 button {  
  all: inherit;    
}

Great, but now the button has no affordance. It doesn't look like it can be activated. This is where, conventionally, a plus/minus symbol is incorporated. Plus indicates that the section can be expanded, and minus that it may be collapsed.

The question is: how do we render the icon? The answer: as efficiently and accessibly as possible. Simple shapes such as rectangles (<rect>) are a highly efficient way to create icons with SVG, so let's do that.

<svg viewBox="0 0 10 10">  
  <rect height="8" width="2" y="1" x="4"/>
  <rect height="2" width="8" y="4" x="1"/>
</svg>  

There, that's small enough to fit in a tweet. Since state is communicated via the aria-expanded attribute non-visually, we don't need this graphic to be screen reader accessible or interactive. In which case, we need to add a couple more attributes.

<button aria-expanded="false">  
  My section
  <svg viewBox="0 0 10 10" aria-hidden="true" focusable="false">
    <rect class="vert" height="8" width="2" y="1" x="4" />
    <rect height="2" width="8" y="4" x="1" />
  </svg>
</button>  

• aria-hidden="true" hides the SVG from screen readers and other assistive technologies
• focusable="false" addresses the issue that Internet Explorer/Edge make SVGs focusable by default

Note the class of "vert" for the rectangle that represents the vertical strut. We're going to target this with CSS to show and hide it depending on the state, transforming the icon between a plus and minus shape.

[aria-expanded="true"] .vert {
  display: none;
}

Tying state and its visual representation together is a very good thing. It ensures that state changes are communicated interoperably. Do not listen to those who advocate the absolute separation of HTML semantics and CSS styles. Form should follow function, and directly is most reliable.

Note that the default focus style was removed with inherit: all. We can delegate a focus style to the SVG with the following.

h2 button:focus svg {  
  outline: 2px solid;
}

High contrast themes

One more thing: We can ensure the <rect> elements respect high contrast themes. By applying a fill of currentColor to the <rect> elements, they change color with the surrounding text when it is affected by the theme change.

[aria-expanded] rect {
  fill: currentColor;
}

To test high contrast themes against your design on Windows, search for High contrast settings and apply a theme from Choose a theme. Many high contrast themes invert colors to reduce light intensity. This helps folks who suffer migraines or photophobia as well as making elements clearer to those with vision impairments.

A small script

Given the simplicity of the interaction and all the elements and semantics being in place, we need only write a very terse script:

(function() {
  const headings = document.querySelectorAll('h2')

  Array.prototype.forEach.call(headings, heading => {
    let btn = heading.querySelector('button')
    let target = heading.nextElementSibling

    btn.onclick = () => {
      let expanded = btn.getAttribute('aria-expanded') === 'true' || false

      btn.setAttribute('aria-expanded', !expanded)
      target.hidden = expanded    
    }
  })
})()

Here's an accompanying CodePen demo:

Progressive enhancement

The trouble with the above script is that it requires the HTML to be adapted manually for the collapsible sections to work. Implemented by an engineer as a component via a template/JSX, this is expected. However, for largely static sites like blogs there are two avoidable issues:

• If JavaScript is unavailable, there are interactive elements in the DOM that don't do anything, with semantics that therefore make no sense.
• The onus is on the author/editor to construct the complex HTML.

Instead, we can take basic prose input (say, written in markdown or in a WYSIWYG) and enhance it after the fact with the script. This is quite trivial in jQuery given the nextUntil and wrapAll methods, but in plain JavaScript we need to do some iteration. Here's another CodePen that automatically adds the toggle button and groups the section content for toggling. It targets all <h2>s found in the <main> part of the page.

Why write it in plain JavaScript? Because modern browsers support Web API methods very consistently now, and because small interactions should not depend on large libraries.

A progressive web component

The last example meant we didn't have to think about our collapsible sections during editorial; they'd just appear automatically. But what we gained in convenience, we lost in control. Instead, what if there was a compromise wherein there was very little markup to write, but what we did write let us choose which sections should be collapsible and what state they should be in on page load?

Web components could be the answer. Consider the following:

<toggle-section open="false">  
  <h2>My section</h2>
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras efficitur laoreet massa. Nam eu porta dolor. Vestibulum pulvinar lorem et nisl tempor lacinia.</p>
  <p>Cras mi nisl, semper ut gravida sed, vulputate vel mauris. In dignissim aliquet fermentum. Donec arcu nunc, tempor sed nunc id, dapibus ornare dolor.</p>
</toggle-section>  

The custom element name is easy to remember, and the open attribute has obvious implications. Better still, where JavaScript is unavailable, this outer element is treated like a mere <div> and the collapsible section remains a simple section. No real harm done.

In fact, if we detect support for the <template> element and attachShadow within our script, the same fallback will be presented to browsers not supporting these features.

if ('content' in document.createElement('template')) {  
  // Define the <template> for the web component

  if (document.head.attachShadow) {
    // Define the web component using the v1 syntax
  }
}

The template

We could place a template element in the markup and reference it, or create one on the fly. I'm going to do the later.

tmpl.innerHTML = `  
  <h2>
    <button aria-expanded="false">
      <svg aria-hidden="true" focusable="false" viewBox="0 0 10 10">
        <rect class="vert" height="8" width="2" y="1" x="4"/>
        <rect height="2" width="8" y="4" x="1"/>
      </svg>
    </button>
  </h2>
  <div class="content" hidden>
    <slot></slot>
  </div>
  <style>
    h2 {
      margin: 0;
    }

    h2 button {
      all: inherit;
      box-sizing: border-box;
      display: flex;
      justify-content: space-between;
      width: 100%;
      padding: 0.5em 0;
     }

    button svg {
      height: 1em;
      margin-left: 0.5em;
    }

    [aria-expanded="true"] .vert {
      display: none;
    }

    [aria-expanded] rect {
      fill: currentColor;
    }
  </style>
`

This template content will become the Shadow DOM subtree for the component.

By styling the collapsible section from within its own Shadow DOM, the styles do not affect elements in Light DOM (the standard, outer DOM). Not only that, but they are not applied unless the browser supports <template> and custom elements.

Defining the component

Note the <slot> element in the template HTML, which is a window to our Light DOM. This makes it much easier to wrap the content provided by the author than in the previous progressive enhancement demo.

Inside the component definition, this.innerHTML refers to this Light DOM content. We shall create a shadowRoot and populate it with the template's content. The Shadow DOM markup is instead found with this.shadowRoot.innerHTML.

class ToggleSection extends HTMLElement {  
  constructor() {
    super()

    this.attachShadow({ mode: 'open' })
    this.shadowRoot.appendChild(tmpl.content.cloneNode(true))
  }
}

With these references, we can move Light DOM to Shadow DOM. Which means we can repurpose the Light DOM <h2>'s label and eliminate the now superfluous element. It probably seems dirty doing this DOM manipulation — especially when you're used to simple, declarative (React) components. But it's what makes the web component progressive.

this.btn = this.shadowRoot.querySelector('h2 button')  
var oldHeading = this.querySelector('h2')  
var label = oldHeading.textContent  
this.btn.innerHTML = label + this.btn.innerHTML  
oldHeading.parentNode.removeChild(oldHeading)  

Actually, we can do one better and support different introductory heading levels. Instead of targeting headings at all, we can just get the first element in the Light DOM. Making sure the first element is a heading would be a matter for editorial guidance. However, if it's not a heading, we can make good of any element — as I shall demonstrate.

var oldHeading = this.querySelector(':first-child')  

Now we just need to make sure the level for the Shadow DOM heading is faithful to the Light DOM original. I can query the tagName of the Light DOM heading and augment the Shadow DOM level with aria-level accordingly.

let level = parseInt(oldHeading.tagName.substr(1))  
this.heading = this.shadowRoot.querySelector('h2')  
if (level && level !== 2) {  
  this.heading.setAttribute('aria-level', level)
}

The second character of tagName is parsed as an integer. If this is a true integer (NaN is falsey) and isn't the 2 offered implicitly by <h2>, aria-level is applied. As a fallback, a non-heading element still gives up its textContent as the label for the extant Shadow DOM <h2>. This can be accompanied by a polite console.warn, advising developers to use a heading element as a preference.

if (!level) {  
  console.warn('The first element inside each <toggle-section> should be a heading of an appropriate level.')
}

One advantage of using aria-level is that, in our case, it is not being used as a styling hook — so the appearance of the heading/button remains unchanged.

<h2 aria-level="3">  
  <button aria-expanded="false">
    <svg aria-hidden="true" focusable="false" viewBox="0 0 10 10">
      <rect class="vert" height="8" width="2" y="1" x="4"/>
      <rect height="2" width="8" y="4" x="1"/>
    </svg>
  </button>
</h2>  

If you wanted your collapsible section headings to reflect their level, you could include something like the following in your CSS.

toggle-section [aria-level="2"] {  
  font-size: 2rem;
}

toggle-section [aria-level="3"] {  
  font-size: 1.5rem;
}

/* etc */

The region role

Any content that is introduced by a heading is a de facto (sub)section within the page. But, as I covered in A Todo List, you can create explicit sectional container elements in the form of <section>. You get the same effect by applying role="region" to an element, such as our custom <toggle-section> (which otherwise offers no such accessible semantics).

<toggle-section role="region">  
  ...
</toggle-section>  

Screen reader users are more likely to traverse a document by heading than region but many screen readers do provide region shortcuts. Adding role="region" gives us quite a bit:

• It provides a fallback navigation cue for screen reader users where the Light DOM does not include a heading.
• It elicits the announcement of "region" when the screen reader user enters that section, which acts as a structural cue.
• It gives us a styling hook in the form toggle-button[role="region"]. This lets us add styles we only want to see if the script has run and web components are supported.

Tethering open and aria-expanded

When the component's open value changes between true and false we want the appearance of the content to toggle. By harnessing observedAttributes() and attributeChangedCallback() we can do this directly. We place this code after the component's constructor:

static get observedAttributes() {  
  return ['open']
}

attributeChangedCallback(name) {  
  if (name === 'open') {
    this.switchState()
  }
}

• observedAttributes() takes an array of all the attributes on the parent <toggle-section> that we wish to watch
• attributeChangedCallback(name) lets us execute our switchState() function in the event of a change to open

The advantage here is that we can toggle state using a script that simply changes the open value, from outside the component. For users to change the state, we can just flip open inside a click function:

this.btn.onclick = () => {  
  this.setAttribute('open', this.getAttribute('open') === 'true' ? 'false' : 'true')
}

Since the switchState() function augments the aria-expanded value, we have tethered open to aria-expanded, making sure the state change is accessible.

this.switchState = () => {  
  let expanded = this.getAttribute('open') === 'true' || false
  this.btn.setAttribute('aria-expanded', expanded)
  this.shadowRoot.querySelector('.content').hidden = !expanded
}

Here's the CodePen for this version of the web component with comments:

Expand/collapse all

Since we toggle <toggle-section> elements via their open attribute, it's trivial to afford users an 'expand/collapse all' behavior. One advantage of such a provision is that users who have opened multiple sections independently can 'reset' to an initial, compact state for a better overview of the content. By the same token, users who find fiddling with interactive elements distracting or tiresome can revert to scrolling through open sections.

It's tempting to implement 'expand/collapse all' as a single toggle button. But we don't know how many sections will initially be in either state. Nor do we know, at any given time, how many sections the user has opened or closed manually.

Instead, we should group two alternative controls.

<ul class="controls" aria-label="section controls">  
  <li><button id="expand">expand all</button></li>
  <li><button id="collapse">collapse all</button></li>
</ul>  

It's important to group related controls together, and lists are the standard markup for doing so. See also: the lists of navigation links discussed in Menus & Menu Buttons. Lists and list items tell screen reader users when they are interacting with related elements and how many of these elements there are.

Some compound ARIA widgets have their own grouping mechanisms, like role="menu" grouping role="menuitem" elements or role="tablist" grouping role="tab" elements. Our use case does not suit either of these paradigms, and a simple labeled list suffices.

Because <ul> is implicitly a 'group' element, many assistive technologies will acknowledge a group label provided to it using aria-label. In VoiceOver, when a user enters the list and focuses the button, they will hear "expand all, button, list, section controls, two items".

Note that using aria-label only provides a non-visual label. This is acceptable if the purpose of the buttons can be gleaned visually through other cues such as layout. In this case, the proximity of the buttons to the sections probably suffices, but testing should be undertaken.

Tracking the URL

One final refinement.

Conventionally, and in the absence of JavaScript enhancement, users are able to follow and share links to specific page sections by their hash. This is expected, and part of the generic UX of the web.

Most parsers add id attributes for this purpose to heading elements. As the heading element for a target section in our enhanced interface may be inside a collapsed/unfocusable section, we need to open that to reveal the content and move focus to it. The connectedCallback() lifecycle lets us do this when the component is ready. It's like DOMContentLoaded but for web components.

connectedCallback() {  
  if (window.location.hash.substr(1) === this.heading.id) {
    this.setAttribute('open', 'true')
    this.btn.focus()
  } 
}

Note that we focus the button inside the component's heading. This takes keyboard users to the pertinent component ready for interaction. In screen readers, the parent heading level will be announced along with the button label.

Further to this, we should be updating the hash each time the user opens successive sections. Then they can share the specific URL without needing to dig into dev tools (if they know how!) to copy/paste the heading's id. Let's use pushState to dynamically change the URL without reloading the page:

this.btn.onclick = () => {  
  let open = this.getAttribute('open') === 'true' || false
  this.setAttribute('open', open ? 'false' : 'true')

  if (this.heading.id && !open) {
    history.pushState(null, null, '#' + this.heading.id)
  }
}

Here's a demo with the hash tracking capability added:

Conclusion

Your role as an interface designer and developer (yes, you can be both at the same time) is to serve the needs of the people receiving your content and using your functionality. These needs encompass both those of 'end users' and fellow contributors. The product should of course be accessible and performant, but maintaining and expanding the product should be possible without esoteric technical knowledge.

Whether implemented through web components or not, progressive enhancement not only ensures the interface is well-structured and robust. As we've seen here, it can also simplify the editorial process. This makes developing the application and its content more inclusive.

Checklist

• Don't depend on large libraries for small interactions, unless the library in question is likely to be used for multiple other interactive enhancements.
• Do not override important element roles. See the second rule of ARIA use.
• Support high contrast themes in your SVG icons with currentColor.
• If the content is already otherwise static, there is a good case for basing your web component on progressive enhancement.
• Do please come up with more descriptive labels for your sections than "Section 1", "Section 2" etc. Those are just placeholders!

As we shall explore, the conceptual boundaries between tab panels, application views, and simple document fragments are not as clearly defined as we might like to pretend. Nonetheless, we need to assert with confidence precisely what kind of interface we are providing the user, otherwise they won't find the confidence to successfully operate it.

Proponents of progressive enhancement conceive interfaces in terms of structured static content before contemplating how those interfaces may become enhanced with additional JavaScript-enabled interactivity. Even if you are happy to concede a JavaScript dependency early in an interface's design, it's beneficial to build a robust foundation using semantic HTML, capitalizing on standard browser behaviors. Sometimes you may even find JavaScript enhancement is a step you needn't take.

For my money, an embryonic tabbed interface is just a table of content with same-page links pointing at different sections of the page. Both a table of content and a list of tabs allow the user to choose between distinct sections of content.

• Table of contents → tab list
• Same-page links → tabs
• Sections → tab panels

CSS enhancement

What if I used some CSS to make just the chosen section from my table of contents visible? This is certainly possible using the :target pseudo-class.

section:not(:target) {  
  display: none;
}

By placing the disclosure of content under the user's control, our CSS-enhanced TOC interface moves towards being a tabbed interface in one critical regard. Since display: none hides content from assistive technologies, this enhancement affects screen reader users as much as anyone else.

Take the TOC links and align them horizontally, then this little CSS experiment begins to really look like a tabbed interface. But herein lies a problem.

In Chapter 2 of his book, Resilient Web Design Jeremy Keith talks about material honesty; that "one material should not be used as a substitute for another." In this case, we'd be making a table of contents appear like a tab list. We should avoid this since users who see tabs expect certain behaviors not offered by a simple list of links.

It is for the same reason that a tabbed design should not be employed for site-wide navigation. At the very least, when a user selects a "tab" they would not expect to be navigated to an entirely new page!

I have encountered innumerable JavaScript-driven and ARIA-adorned, fully-fledged tabbed interfaces where simple tables of content atop page sections would have done just as well. Better even, since they are more robust and efficient. But for goodness' sake make them look like tables of content. Meet the expectations you set in visual design with your semantics and behaviors.

True tabbed interfaces

The advantage of using lists of same-page links and the standard browser behaviors they invoke is that they are simple and easy to understand — especially since the behavior of links is peculiar to the web.

Tabbed interfaces, on the other hand, are a paradigm imported from desktop applications. If they are understood by users in the context of web pages at all it is only through very careful and deliberate exposition of visual design and ARIA semantics.

What makes a tabbed interface a tabbed interface is in the ergonomics of its keyboard behavior. Really the only reason the ARIA semantics need be present is to alert screen reader users to the keyboard behaviors they should expect. Here is the basic semantic structure with notes to follow:

<ul role="tablist">  
  <li role="presentation">
    <a role="tab" href="#section1" id="tab1" aria-selected="true">Section 1</a>
  </li>
  <li role="presentation">
    <a role="tab" href="#section2" id="tab2">Section 2</a>
  </li>
  <li role="presentation">
     <a role="tab" href="#section3" id="tab3">Section 3</a>
  </li>
</ul>  
<section role="tabpanel" id="section1" aria-labelledby="tab1">  
  ...
</section>  
<section role="tabpanel" id="section2" aria-labelledby="tab2" hidden>  
  ...
</section>  
<section role="tabpanel" id="section3" aria-labelledby="tab3" hidden>  
  ...
</section>  

• This tabbed interface is progressively enhanced from a table of content and corresponding document sections. In some cases this means adding (aria-selected) or overriding (role="tab") semantics. In others (role="presentation") it means removing semantics that are no longer applicable or helpful. You don't want a set of tabs to also be announced as a plain list.
• role="tablist" does not delegate semantics to its children automatically. It must be used in conjunction with individual tab roles in order for tabs to be identified and enumerated in assistive technologies.
• The tabpanel elements which do not correspond to the selected tab are hidden using the hidden attribute/property.
• Users who enter a tabpanel should be assured of its identity. Hence, aria-labelledby is used to label the panel via the tab name. In practice, this means a screen reader user entering a panel and focusing a link will hear something like "Section 1 tab panel, [link label] link".

Keyboard behavior

Unlike a same-page link, a tab does not move the user to the associated section/panel of content. It just reveals the content visually. This is advantageous to sighted users (including sighted screen reader users) who wish to flit between different sections without having to wade back up the page each time they want to choose a new one.

This comes with an unfortunate side effect: If the user wishes to move to a section by keyboard and interact with its internal content, they have to step through any tabs to the right of the current tab, which are in focus order.

This problem is solved by delegating tab selection to arrow keys. The user is able to select and activate tabs using the arrow keys, while the Tab key is preserved for focusing contents within and below the active tab panel. To put it another way: Tab is not for tabs, which I concede is a bit confusing. I wish the key and the control had different names, but alas.

It's equally important that pressing Shift + Tab returns the user to the selected tab. This is all possible by giving each tab but the selected tab tabindex="-1", which removes the inactive tabs from focus order but allows focus via a script. In the following example, the second tab is the selected tab, as denoted by the aria-selected state being set to true.

<ul role="tablist">  
  <li role="presentation">
    <a role="tab" tabindex="-1" href="#section1">Section 1</a>
  </li>
  <li role="presentation">
    <a role="tab" href="#section2" aria-selected="true">Section 2</a>
  </li>
  <li role="presentation">
     <a role="tab" tabindex="-1" href="#section2">Section 3</a>
  </li>
</ul>  

With tabindex="-1" in place for the remaining tabs, I can capture the keydown event for the left or right arrow keys to make the desired inactive tab active.

tab.addEventListener('keydown', e => {  
  let dir = e.which === 37 ? 'left' : 39 ? 'right' : null;
  if (dir) {
    switchTab(e.eventTarget, dir);
  }  
})

Each time a user selects a new tab, the corresponding tab panel is revealed. When the second of four tabs is selected, any screen reader running will say something similar to "[tab label], selected, tab, 2 of 4". Plentiful information.

A problem reading panels

Now that pressing Tab bypasses the tabs, it's trivial for keyboard users to move focus to the first of any links or other interactive elements in the open panel.

The experience for screen reader users is not currently as optimal. Although they too can focus elements inside the panel directly from the selected tab, blind users cannot see any content that comes before or after that interactivity. If there is no interactive content in the panel at all, they will unwittingly focus the first interactive element outside and below the tab interface.

In the operation of screen readers like NVDA and JAWS, the down arrow moves the user to the next element (focusable or otherwise) and reads it out. Without intervention, this would be the next tab in the tablist. Instead, we can intercept the down arrow key press and move focus programmatically to the open panel itself, making sure it isn't missed. See panels[i].focus() in the following snippet:

tab.addEventListener('keydown', e => {  
  let index = Array.prototype.indexOf.call(tabs, e.currentTarget);
  let dir = e.which === 37 ? index - 1 : e.which === 39 ? index + 1 : e.which === 40 ? 'down' : null;
  if (dir !== null) {
    e.preventDefault();
    dir === 'down' ? panels[i].focus() : tabs[dir] ? switchTab(e.currentTarget, tabs[dir]) : void 0;
  }
});

The void 0 part means "do nothing" for the case that the adjacent tab does not exist (because you're already at the start or end of the tablist). You can see the full script in the CodePen demo.

Since tab panels are labeled by their tabs, when the down arrow is pressed and the relevant tab panel focused, a screen reader will announce, "[tab label], tab panel", thereby assuring the user of their new location within the interface. From there, they can continue to browse down through the tab panel's descendant elements or press Shift + Tab to return to the tablist and the selected tab.

Although sighted keyboard users are less likely to use the down arrow key, it's important the focused tab panel has a focus style to indicate a change of focus location. This focusable panel provision does not impede operation for sighted keyboard users, who can do everything they need with just the Tab and left and right arrow keys.

Here is a codePen of the tab interface, written in native JavaScript and with the behaviors and semantics discussed. It is progressively enhanced from a list of links and <section> elements and is 1.3KB minified as ES5:

Responsive design

Responsive design is inclusive design. Not only is a responsive design compatible with a maximal number of devices, but it's also sensitive to a user's zoom settings. Full-page zoom triggers @media breakpoints just as narrowing the viewport does.

A tabbed interface needs a breakpoint where there is insufficient room to lay out all the tabs horizontally. The quickest way to deal with this is to reconfigure the content into a single column.

This can no longer be considered a "tabbed interface" visually because the tabs no longer look like tabs. This is not necessarily a problem so long as the selected tab (well, "option") is clearly marked. Non-visually, via screen readers, it presents and behaves the same.

When panels are views

You'll recall my note from earlier that making the set of links in site navigation appear like a set of tabs is deceptive: A user should expect the keyboard behaviors of a tabbed interface, as well as focus remaining on a tab in the current page. A link pointing to a different page will load that page and move focus to its document (body) element.

What about the "views" in single-page applications: the different screens found at different routes? Technically, they are closer to the panels of our tab interface than whole web pages. But that's not to say they should be communicated as tab panels, because that's not what a user is likely to expect.

Single-page application views are typically intended to seem like distinct web pages or regions in a web page, so that is the story that should be told. Here are some provisions to make:

Use links!

Make sure the links that allow users to choose between views are indeed links — whether or not those links return false and use JavaScript to switch to the new view. Since these controls will navigate the user (by changing their focus location; see below) the link role is the most appropriate for the behavior. Link elements do not need the link ARIA role attribute; they are communicated as "link" by default.

In Xiao, a progressive enhancement-based router system for single-page applications, standard hash fragments are used to denote views. The links to these fragments will be communicated as "same page links" in most assistive software. By capitalizing on standard browser behavior, the user will be made aware they are being redirected to a new, distinct part of the page/application.

<a href="#some-route">Some route</a>  

Manage focus

Just replacing some content on the page does not automatically move the user to that content or (in the case of blind assistive technology users) alert them to its existence. As covered under The focus of non-interactive elements above, you can focus the principle heading of the new route view, or the outer view element. If you are focusing the outer view element, it is recommended it is labeled either directly using aria-label or by the principle heading using aria-labelledby.

<div aria-label="Home" role="region" tabindex="-1">  
  ...
</div>  

When used in conjunction with the region role (as in the above code snippet), when the element is focused the contextual information "Home, region" will be announced in screen readers.

Using Xiao, no region is focused on initial page load. This means focus defaults to the body/document element and the <title> is announced in screen readers (see below).

Update the <title>

The application name should be appended by the label for the specific view. This conforms to the recommended pattern for static sites where the site name is appended by the page name.

<title>[Application name] | [View name]</title>  

You can load a Xiao-routed application at any route by simply including the route's hash fragment in the URL. On the load event, the <title> takes that route's label and screen readers identify the application and the specific route within it.

Conclusion

JavaScript can show and hide or create and destroy content with ease, but these DOM events can have different purposes and meanings depending on the context. In this article, we facilitated the basic show/hide ability of JavaScript to create two quite different interfaces: a tabbed interface and single-page application navigation.

There's really no right or wrong in inclusive design. It's just about trying your hardest to provide a valuable experience to as many people as you can. A large part of this is pairing your presentation and behavior in ways that users — no matter how they are operating or reading your interface — would expect for the task in hand.

Checklist

• Don't provide tabbed interfaces unless they are suited to the use case and are likely to be understood and appreciated by the user. Just because you can doesn't mean you should.
• Tables of content and same-page links are a simpler and more robust approach to many of the ostensible use cases for tabbed interfaces.
• Make sure interfaces that appear as tabbed interfaces have the semantics and behaviors expected of them.
• Single-page applications should not present or behave as tabbed interfaces, despite their shared use of JavaScript to switch between and/or populate content panes.

Offering users choices over the display of your interface is friendly, so long as it isn't intrusive. It helps to satisfy the Offer choice inclusive design principle. However, choices such as theme options are nice-to-haves and should only be implemented if it's possible to do so efficiently.

Typically, alternative themes are offered as separate stylesheets that can be switched between using JavaScript. In some cases they represent a performance issue (because an override theme requires loading a lot of additional CSS) and in most cases they represent a maintenance issue (because separate stylesheets have to be kept up to date as the site is further developed).

One of the few types of alternative theme that adds real value to users is a low light intensity "night mode" theme. Not only is it easier on the eyes when reading in the dark, but it also reduces the likelihood of migraine and the irritation of other light sensitivity disorders. As a migraine sufferer, I'm interested!

In this article, I'll be covering how to make an efficient and portable React component that allows users to switch a default light theme into "dark mode" and persist this setting using the localStorage API.

Given a light theme (predominantly dark text on light backgrounds) the most efficient course of action is not to provide a completely alternative stylesheet, but to augment the existing styles directly, as tersely as possible. Fortunately, CSS provides the filter property, which allow you to invert colors. Although this property is often associated with image elements, it can be used on any elements, including the root <html> element:

:root {
   filter: invert(100%);
}

(Note: Some browsers support invert() as a shorthand, but not all, so write out 100% for better support.)

The only trouble is that filter can only invert stated colors. Therefore, if the element has no background color, the text will invert but the implicit (white) background will remain the same. The result? Light text on a light background.

This is easily fixed by stating a light background-color.

:root {
   background-color: #fefefe;
   filter: invert(100%);
}

But we may still run into problems with child elements that also have no stated background color. This is where CSS's inherit keyword comes in handy.

:root {
   background-color: #fefefe;
   filter: invert(100%);   
}

* {
   background-color: inherit;
}

On first impression, this may seems like a lot of power we're wielding, but never fear: the * selector is very low specificity, meaning it only provides a background-color to elements for which one isn't already stated. In practice, #fefefe is just a fallback.

Preserving raster images

While we are intent on inverting the theme, we're probably not going to want to invert raster images or videos, otherwise the design will become filled with spooky looking negatives. The trick here is to double-invert <img/> tags. The selector I'm using excludes SVG images, because — typically presented as flat color diagrams — they should invert successfully and pleasantly.

:root { 
   background-color: #fefefe;
   filter: invert(100%);
}

* { 
   background-color: inherit;
}

img:not([src*=".svg"]), video {  
   filter: invert(100%);
}

Clocking in at 153 bytes uncompressed, that's dark theme support pretty much taken care of. If you're not convinced, here's the CSS applied to some popular news sites:

The theme switch component

Since the switch between light (default) and dark (inverted) themes is just an on/off, we can use something simple like the toggle buttons we explored in an earlier article. However, this time we'll implement the toggle button as part of a React component. There are a few reasons for this:

• Maximum reusability between the React-based projects many of you are used to working in
• Ability to take advantage of React's props and defaultProps
• Some people think frameworks like React and Angular preclude you from writing accessible HTML somehow, and that falsehood needs to die

We're also going to incorporate some progressive enhancement, only showing the component if the browser supports filter: invert(100%).

Setting up

If you don't already have a setup for React development, you can create one easily using create-react-app.

npm i -g create-react-app  
create-react-app theme-switch  
cd theme-switch  
npm start  

The boilerplate app will now be running at localhost:3000. In the new theme-switch project, our component will be called ThemeSwitch and will be included in App.js's render function as <ThemeSwitch></ThemeSwitch>.

class App extends Component {  
  render() {
    return (
      <div className="App">
        <div className="App-header">
          <img src={logo} className="App-logo" alt="logo" />
          <h2>Welcome to React</h2>
        </div>
        <p className="App-intro">
          To get started, edit {gfm-js-extract-pre-1} and save to reload.
        </p>
        <ThemeSwitch></ThemeSwitch>
      </div>
    );
  }
}

(Note: I'm being lazy and leaving the boilerplate in. To really test the theme switcher, include it alongside a bunch of styled content pulled in from another project. You can include CSS in App.css.)

Don't forget to import the ThemeSwitch component at the top of this App.js file:

import ThemeSwitch from './components/ThemeSwitch.js'  

The skeleton component file

As implied by the path in that last import line, we'll be working on a file called ThemeSwitch.js, placed in a new "components" folder, so you'll need to create both the folder and the file. The skeleton for ThemeSwitch looks like this:

import React, { Component } from 'react';

class ThemeSwitch extends Component {  
  render() {
    // The component's markup, in JSX
  }
}

export default ThemeSwitch;  

The rendered markup for the switch, imagined in a default/inactive state, would look like this (notes to follow):

<div>  
   <button aria-pressed="false">
      dark theme:
      <span aria-hidden="true">off</span>
   </button>
   <style media="none">
      html { filter: invert(100%); background: #fefefe }
      * { background-color: inherit }
      img:not([src*=".svg"]), video { filter: invert(100%) }
   </style>
</div>  

• Not all toggle buttons are created the same. In this case, we're using aria-pressed to toggle accessible state and an explicit "on"/"off" for sighted users. So that the "on" or "off" part is not read out to contradict the state, it is suppressed from assistive technologies with aria-hidden. Screen reader users will hear "dark theme toggle button, not pressed" or "dark theme toggle button, pressed" or similar.
• The CSS is so terse, we're going to provide it as an embedded stylesheet. This is set to media="none" — or media="screen" when the dark theme is activated

This markup will get very messy shortly, as we convert it to JSX.

Switching state

Our component will be stateful, allowing the user to toggle the dark theme between inactive and active. First we initialize the state on the component's constructor:

constructor(props) {  
   super(props);

   this.state = {
      active: 'false'
   };
}

To bring things to life, a helper function called isActive() is included, along with a toggle() function that actually toggles the state:

  isActive = () => this.state.active === true;

  toggle = () => {
    this.setState({
      active: !this.isActive()
    });
  }

(Note: Arrow functions implicitly return single statements, hence the tersity of the isActive() function.)

In the render function for the component, we can use isActive() to switch the aria-pressed value, the button text, and the value of the stylesheet's media attribute:

return (  
  <div>
    <button aria-pressed={this.isActive()} onClick={this.toggle}>
      dark theme:
      <span aria-hidden="true">{this.isActive() ? 'on' : 'off'}</span>
    </Button>
    <style media={this.isActive() ? 'screen' : 'none'}>
      {this.css}
    </style>
  </div>
);

Note the {this.css} part. JSX doesn't support embedding CSS directly, so we have to save it to a variable and enter it here dynamically. In the constructor:

this.css = `  
html { filter: invert(100%); background: #fefefe; }  
* { background-color: inherit }
img:not([src*=".svg"]), video { filter: invert(100%) }`;  

Overcoming browser issues

Unfortunately, just switching between media="none" and media="screen" does not apply the styles to the page in all browsers. To force a repaint, it turns out we have to rewrite the text content of the <style> tag. The easiest way I found of doing this was to incorporate the trim() method. Curiously, this only seemed to be needed in Chrome.

{this.isActive() ? this.css.trim() : this.css}

Persisting the theme preference

To persist the user's choice of theme, we can use localStorage and React lifecycle methods. First, I'll set an alias for localStorage on the constructor. This suppresses linting errors produced when calling localStorage directly.

this.store = typeof localStorage === 'undefined' ? null : localStorage;  

Using the componentDidMount method, I can fetch and apply the saved setting after the component mounts to the page. The expression defaults the value to 'false' if the storage item is yet to be created.

componentDidMount() {  
  if (this.store) {
    this.setState({
      active: this.store.getItem('ThemeSwitch') || false
    });
  }
}

Because state is managed asynchronously in React, it's not reliable to simply save a changed state after it has been augmented. Instead, I need to use the componentDidUpdate method:

componentDidUpdate() {  
  if (this.store) {
    this.store.setItem('ThemeSwitch', this.state.active);
  }
}

Hiding from unsupporting browsers

Some browsers are yet to support filter: invert(100%). For those browsers, we will hide our theme switch altogether. It's better that it is not available than it is available and doesn't work. With a special invertSupported function, we can query support to set a supported state.

If you've ever used Modernizr you might have used a similar CSS property/value test. However, we don't want to use Modernizr because we don't want our component to rely on any dependencies unless completely necessary.

invertSupported (property, value) {  
  var prop = property + ':',
      el = document.createElement('test'),
      mStyle = el.style;
  el.style.cssText = prop + value;
  return mStyle[property];
}

componentDidMount() {  
  if (this.store) {
    this.setState({
      supported: this.invertSupported('filter', 'invert(100%)'),
      active: this.store.getItem('ThemeSwitch') || false
    });
  }
}

This can be used in our JSX to hide the component interface using the hidden property where support returns false:

<div hidden={!this.state.supported}>  
  <!-- component contents here -->
</div>  

In modern browsers, the hidden property will hide the component from assistive technologies and make it unfocusable by keyboard. To make sure older browsers have the same behavior, include the following in your stylesheet:

[hidden] {
  display: none;
}

Alternatively, you can refuse to render the component contents to the page at all, by returning null.

render() {  
  if (!this.supported) {
    return null;
  }

  return (
    <div>
      <button aria-pressed={this.state.active} onClick={this.toggle}>
        inverted theme: <span aria-hidden="true">{this.state.active ? 'on' : 'off'}</span>
      </button>
      <style media={this.state.active ? 'screen' : 'none'}>
        {this.state.active ? this.css.trim() : this.css}
      </style>
    </div>
  );
}

The preserveRasters prop

Props (component properties) are the standard way to make components configurable. A configurable component can be used in a greater variety of situations and projects and is therefore more inclusive.

In our case, why don't we make it so that the implementor has a choice over whether raster images are indeed preserved, or if they're inverted with everything else. I'll create a preserveRasters prop that takes "true" or "false" values. Here's how it looks on our component:

<ThemeSwitch preserveRasters={false} />  

I can query this prop in the formulation of the CSS string, and only re-invert images if its value is "true":

this.css = `  
  html { filter: invert(100%); background: #fefefe; }
  * { background-color: inherit }
  ${this.props.preserveRasters === 'true' ? `img:not([src*=".svg"]), video { filter: invert(100%) }` : ``}`;

(Note: It's quite possible, though slightly ugly, to use ternaries during string interpolation in this way.)

The default value

To make the component more robust and offer the implementor the option of omitting the prop attribute, we can also supply a defaultProp. The following can be supplied after the component class definition:

ThemeSwitch.defaultProps = { preserveRasters: true }  

Installing the component

A version of this component is available on NPM:

npm i --save react-theme-switch  

In addition, a plain JavaScript version, based on a checkbox element, is available to play with in the following codePen:

Placement

The only thing left to do is decide where you're going to put the component in the document. As a rule of thumb, utilities like theme options should be found in a landmark region — just not the <main> region, because the screen reader user expects this content to change between pages. The <header> (role="banner") or <footer> (role="contentinfo") are both acceptable.

The switch should appear in the same place on all pages so that, once the user has located it once, they can easily find it again. Take note of the Be consistent inclusive design principle, which applies here.

Checklist

• Only implement nice-to-have features if the performance hit is minimal and the resulting interface does not increase significantly in complexity
• Only provide interfaces for supported features. Use feature detection.
• Use semantic HTML in your React components — they'll still work!
• Use props to make your components more configurable and reusable

When and how these bubbles transpire is apparently up for debate, since I've encountered many a tooltip and they all seem to behave slightly differently. I've come to the conclusion that these numerous implementations fall into two distinct groups: true tooltips, and a pattern I'm hesitantly calling the "toggletip", coined by the aforementioned Steve in some research and experimentation he did not long ago.

Inclusive design is often about providing the user with the right tool for the job, and the right kind of tooltip to go with that tool. In this article, I'll be looking at situations which might call for a tooltip or else a toggletip, and formulating inclusive implementations for each.

The title attribute

We can't talk about tooltips without bringing up the title attribute: the HTML standard for providing contextual information bubbles. The Paciello Group blog pulls no punches in describing the title attribute's contribution to web interfaces:

"If you want to hide content from mobile and tablet users as well as assistive tech users and keyboard only users, use the title attribute." — The Paciello Group blog

That's pretty bad in terms of inclusion. In fact, the only place I can think of where the title attribute works reliably in screen reader software is on form elements like <input>s. Even then, touch and keyboard users won't get to see the title message appear. In short: just provide a clearly worded, permanently visible label.

I'm a big supporter of using standard HTML elements and attributes wherever they're available. It's the most efficient and performant way to build usable web interfaces. But, despite being a specification mainstay, the title attribute really isn't fit for purpose.

Then again, we've yet to define that purpose. What should tooltips be used for? And even if we can design them to be usable by the many, do we need them at all?

A case for tooltips

As we already established, tooltips are for clarification; they are for providing missing information. But why should that information be missing in the first place? As I wrote in Inclusive Design Patterns, icons can accelerate the understanding of an interface, and help to internationalize it. But icons provided in isolation are always in danger of completely confounding a user — because they don't spell anything out. To users who don't recognize or can't decipher the icon, information is missing.

Most of the time, you should simply be providing text alongside icons. Like the perma-visible field labels I just mentioned, textual labels are the most straightforward way of labeling things and they're automatically screen reader accessible if provided as real text (not images of text).

The usual excuse for not providing textual labels is, "there's no space". And there likely isn't, if you set out not to include textual labels in the first place. If you treat them as important from the beginning, you will find a way.

Tooltips are a last resort, where space really is at a premium — perhaps due to the sheer number of controls, like in the toolbar for a WYSIWYG editor. So, how would we go about designing them to be as inclusive as possible?

Inclusive tooltips

The first thing to get right is making the text in the tooltip accessible to assistive technologies. There are a couple of different methods for associating the tooltip to the focused control, and we choose between them based on the specific role of that tooltip: Is the tooltip there to provide a primary label or an auxiliary clarification?

A notifications control with a tooltip reading "Notifications" treats the tooltip as a primary label. Alternatively, a tooltip that reads "View notifications and manage settings" is supplementary.

Tooltip as primary label

To associate one element with another as its primary label, you can use aria-labelledby. The relationship is forged by the aria-labelledby and id attributes sharing the same value.

<button class="notifications" aria-labelledby="notifications-label">  
  <svg><use xlink:href="#notifications-icon"></use></svg>
</button>  
<div role="tooltip" id="notifications-label">Notifications</div>  

• Note the use of the tooltip role. In practical terms, all this role offers is an assurance that aria-describedby works reliably where supported. As Léonie Watson writes, ARIA labels and descriptions sometimes don't work with all elements unless you incorporate an appropriate role. In this case, the most important role is the implicit button role of the subject <button> element, but role="tooltip" may extend support for this labeling method in some software.
• Whatever text content is in the linked SVG, it won't be read out. The aria-labelledby association supersedes the text content of the button as the label.

To a screen reader — and its user — the above is now functionally similar to using a simple text label, like this:

<button class="notifications">Notifications</button>  

The tooltip text is available on focus, just as it would be on hover for sighted users. In fact, if all text appeared only on hover, a sighted mouse user's experience of an interface would be somewhat analogous to that of a blind screen reader user.

Including notification count

What if the notifications button showed a count of unread notifications, as these things often do (I'm thinking, of course, of Twitter)?

Fortunately, aria-labelledby can accept multiple, space separated ids.

<button class="notifications" aria-labelledby="notifications-count notifications-label">  
  <svg><use xlink:href="#notifications-icon"></use></svg>
  <span id="notifications-count">3</span>
</button>  
<div role="tooltip" id="notifications-label">Notifications</div>  

Despite the #notifications-count element appearing inside the <button>, it does not form the label by itself: It forms the first part of the label as the first id listed in the aria-labelledby value. It is placed where it is so that the designer can take advantage of relative and absolute positioning to arrange the element visually.

To screen reader users, the label is now "3 notifications". This succinctly acts as both a current count of notifications and a reminder that this is the notifications control.

Tooltip as auxiliary description

Now let's try setting up the tooltip as a supplementary description, which is the archetypal form. Like <input> placeholders, tooltips should be for added information and clarification.

Some interactive elements may have accessible descriptions, but all interactive elements need accessible labels. If we're using aria-describedby to connect the tooltip text, we'll need another method for providing the "Notifications" label. Instead of aria-labelledby we can add a visually hidden span to the button's text node, alongside the existing "3" counter.

<button class="notifications" aria-describedby="notifications-count notifications-label">  
  <svg><use xlink:href="#notifications-icon"></use></svg>
  <span id="notifications-count">3</span> 
  <span class="visually-hidden">Notifications</span>
</button>  
<div role="tooltip" id="notifications-label">View and manage notifications settings</div>  

The visually-hidden class corresponds to some special CSS we've discussed before on Inclusive Components. It hides the <span> visually without stopping it from being read out in screen readers.

.visually-hidden {
  clip-path: inset(100%);
  clip: rect(1px, 1px, 1px, 1px);
  height: 1px;
  overflow: hidden;
  position: absolute;
  white-space: nowrap;
  width: 1px;
}

The prescribed behavior of aria-describedby is to be announced as the last piece of information for the control, after the label and role. In this case: "Notifications button… View and manage notifications settings" (most screen readers will leave a pause before the description).

Interaction

To improve upon the notoriously awful title attribute, our custom tooltips should appear on focus as well as hover. By supplying the tooltip in an element adjacent to the button, we can do this with just CSS:

[role="tooltip"] {
  display: none;
}

button:hover + [role="tooltip"],  
button:focus + [role="tooltip"] {  
  display: block;
}

However, we may need to wrap the button and tooltip in a container element for positioning purposes:

.button-and-tooltip {
  position: relative;
}

[role="tooltip"] {
  position: absolute;
  /* left/top/right/bottom values as required */
}

Touch interaction

So far this simply doesn't work so well for touch screen users because the focus and active states happen simultaneously. In practice, this means you'll see the tooltip, but only as the button is being pressed.

How much of a problem this is depends on the nature of the app to which the control belongs. How bad is it if the user presses the control without really knowing what it does the first time? How easily can they recover?

There are other things you could try, of course. One might be to suppress the button's action on the first press so it just shows the tooltip that time around. You could take this "tutorial mode" idea further still and show the tooltips as inline text for newcomers, but streamline the interface to just show icons for established users. By then, they should have learned what the icons represent.

This would be to do away with tooltips altogether, which is probably for the best anyway. However, the tooltip's sister component — the toggletip — can work for mouse, keyboard and touch users.

Inclusive toggletips

Toogletips are like tooltips in the sense that they can provide supplementary or clarifying information. However, they differ by making the control itself supplementary: toggletips exist to reveal information balloons, and serve no other purpose.

Often they take the form of little "i" icons:

To work by touch just as well as by mouse or keyboard, toggletips are revealed by click rather than by hover and focus. Crucially, this means the aria-describedby association is no longer appropriate. Why? Because a screen reader user would have access to the information before pressing the button, so pressing it would appear not to do anything. Technically, they have access to the information, making the control "accessible" — but the control simply wouldn't make sense. In other words, it's a user experience issue more than a strict accessibility one, but it's important.

Toggletips with live regions

The trick is to make screen readers announce the information after the click event. This is a perfect use case for a live region. We can supply an empty live region, and populate it with the toggletip "bubble" when it is invoked. This will both make the bubble appear visually and cause the live region to announce the tooltip's information.

To follow is the markup with the live region unpopulated. Note the .tooltip-container element, which is provided to help positioning. This element would have position: relative, allowing for absolutely positioning the generated .toggletip-bubble element nearby.

<span class="tooltip-container">  
  <button type="button" aria-label="more info" data-toggletip-content="This clarifies whatever needs clarifying">i</button>
  <span role="status"></span>
</span>  

Note the type="button" attribution which is to stop some browsers mistaking the button as a submit button when placed inside forms. Here is the markup with the live region populated (after the toggletip button is clicked):

<span class="tooltip-container">  
  <button type="button" aria-label="more info" data-toggletip-content="This clarifies whatever needs clarifying">i</button>
  <span role="status">
    <span class="toggletip-bubble">This clarifies whatever needs clarifying</span>
  </span>
</span>  

The accompanying script and codePen, with notes to follow:

(function() {
  // Get all the toggletip buttons
  var toggletips = document.querySelectorAll('[data-toggletip-content]');

  // Iterate over them
  Array.prototype.forEach.call(toggletips, function (toggletip) {
    // Get the message from the data-content element
    var message = toggletip.getAttribute('data-toggletip-content');

    // Get the live region element
    var liveRegion = toggletip.nextElementSibling;

    // Toggle the message
    toggletip.addEventListener('click', function () {
        liveRegion.innerHTML = '';
        window.setTimeout(function() {
          liveRegion.innerHTML = '<span class="toggletip-bubble">'+ message +'</span>';
        }, 100);
    });

    // Close on outside click
    document.addEventListener('click', function (e) {
      if (toggletip !== e.target) {
        liveRegion.innerHTML = '';
      }                        
    });

    // Remove toggletip on ESC
    toggletip.addEventListener('keydown', function(e) {
      if ((e.keyCode || e.which) === 27)
      liveRegion.innerHTML = '';
    });
  });
}());

Notes

• Our button is not a toggle button — at least, not in the usual sense. Instead of clicking the button showing or hiding the bubble, it only shows it. Hiding the bubble is achieved by unfocusing the button, mouse clicking away from the button or pressing escape.
• When the button is clicked for a second (or third, fourth etc.) time, the live region is repopulated after a discreet interval, re-announcing the content in screen readers. This is simpler and more intuitive than implementing toggle states (a "message in on" state makes little sense, especially once it has already been read out).
• The "discreet interval" (see last item) is implemented using setTimeout. Without it, some setups are not able to register the repopulation of the live region and do not re-announce the contents.
• The role="tooltip" attribution is not applicable since we are using role="status" for the live region.

Progressively enhancing title

As discussed, the title attribute is really flaky. But it does at least provide an accessible label to some assistive technologies, available when the button is focused. We could provide the bubble content via title and use this to build the data-toggletip-content attribute on page load. Our script's initial hook now becomes the boolean data-toggletip:

<button data-toggletip aria-label="more info" title="This clarifies whatever needs clarifying">i</button>  

In the script, we need to take the value from title to build data-tooltip-content, then destroy title because we don't need it and it might still appear / get announced if left festering.

var toggletips = document.querySelectorAll('[data-toggletip][title]');

Array.prototype.forEach(toggletips, function (toggletip) {  
  var message = toggletip.getAttribute('title');
  toggletip.setAttribute('data-tooltip-content', message);
  toggletip.removeAttribute('title');
});

Better progressive enhancement

A button that doesn't do anything and happens to have a title attribute isn't really a very good baseline. Instead, I would recommend displaying the toggletip's content inline and then enhancing by creating the toggletip button dynamically.

Here's another codePen, which progressively enhances a simple paragraph into a toggletip:

Tests and error messages

Something I haven't talked about on Inclusive Components is writing tests, so let's do a little of that here. Don't worry, I don't mean unit tests.

If our toggletip component is to belong to a design system, it may be borrowed and used by lots of different people. By writing tests and including warnings, we can try to ensure it isn't being used improperly.

A toggletip button that isn't a <button> provides a deceptive role to assistive technologies and is not focusable by keyboard (unless it's another, inappropriate focusable element like a hyperlink). In our script, we can detect the element nodeName and return an error message if it is not BUTTON. We use return to stop the remainder of the IIFE (Immediately Invoked Function Expression) from executing.

if (toggletip.nodeName !== 'BUTTON') {  
  console.error('Toggletip buttons need to be <button> elements.')
  return;
}

CSS tests and error messages

In Inclusive Design Patterns I write about creating deliberate visual regressions to highlight code errors, and providing error messages in the developer tools CSS inspector.

The error we caught with JavaScript earlier can be caught using the CSS selector [data-tooltip]:not(button). We can highlight the erroneous element with a red outline, and provide an error message using the made-up ERROR property:

[data-tooltip]:not(button) {
  outline: red solid 0.5em;
  ERROR: Toggletip buttons need to be <button> elements.
}

Despite being an invalid property, the ERROR will appear in dev tools when the element is inspected.

Conclusion

Most of the time, tooltips shouldn't be needed if you provide clear textual labeling and familiar iconography. Most of the time toggletips are a complex way of providing information that could just be part of the document's prose content. But I see each of these components all the time in auditing websites, so I wanted to provide some guidance on how to make the most of them.

Checklist

• If you have space, don't use tooltips or toggletips. Just provide clear labels and sufficient body text.
• If it's a tooltip you are looking to use, decide whether the tip's content should be provided as the label or description and choose ARIA properties accordingly.
• Don't rely on title attributes. They are not keyboard accessible and are not supported in many screen reader setups.
• Don't describe toggletips with aria-describedby. It makes the subject button non-functional to screen reader users.
• Don't put interactive content such as close and confirm buttons or links in tooltips or toggletips. This is the job of more complex menu and dialog components.

In design, we often make the same mistake of giving different things the same name. They appear similar, but appearances can be deceptive. This can have an unfortunate effect on the clarity of your component library. In terms of inclusion, it may also lead you to repurpose a semantically and behaviorally inappropriate component. Users will expect one thing and get another.

The term “dropdown” names a classic example. Lots of things “drop down” in interfaces, including the set of <option>s from a <select> element, and the JavaScript-revealed list of links that constitute a navigation submenu. Same name; quite different things. (Some people call these “pulldowns”, of course, but let’s not get into that.)

Dropdowns which constitute a set of options are often called “menus”, and I want to talk about these here. We shall be devising a true menu, but there’s plenty to be said about not-really-true menus along the way.

Let’s start with a quiz. Is the box of links hanging down from the navigation bar in the illustration a menu?

The answer is no, not a true menu.

It’s a longstanding convention that navigation schemas are composed of lists of links. A convention nearly as longstanding dictates that sub-navigation should be provided as nested lists of links. If I were to remove the CSS for the component illustrated above, I should see something like the following, except colored blue and in Times New Roman.

• Home
• About
• Shop
  • Dog costumes
  • Waffle irons
  • Magical orbs
• Contact

Semantically speaking, nested lists of links are correct in this context. Navigation systems are really tables of content and this is how tables of content are structured. The only thing that really makes us think “menu” is the styling of the nested lists and the way they are revealed on hover or focus.

That’s where some go wrong and start adding WAI-ARIA semantics: aria-haspopup="true", role="menu", role="menuitem" etc. There is a place for these, as we’ll cover, but not here. Here are two reasons why:

1. ARIA menus are not designated for navigation but for application behavior. Imagine the menu system for a desktop application.
2. The top-level link should be usable as a link, meaning it does not behave like a menu button.

Regarding (2): When traversing a navigation region with submenus, one would expect each submenu to appear upon hovering or focusing the “top level” link (“Shop” in the illustration). This both reveals the submenu and places its own links in focus order. With a little help from JavaScript capturing focus and blur events to persist the appearance of the submenus while needed, someone using the keyboard should be able to tab through each link of each tier, in turn.

Menu buttons which take the aria-haspopup="true" property do not behave like this. They are activated on click and have no other purpose than to reveal a secreted menu.

As pictured, whether that menu is open or closed should be communicated with aria-expanded. You should only change this state on click, not on focus. Users do not usually expect an explicit change of state on a mere focus event. In our navigation system, state doesn’t really change; it’s just a styling trick. Behaviorally, we can Tab through the navigation as if no such show/hide trickery were occurring.

The problem with navigation submenus

Navigation submenus (or “dropdowns” to some) work well with a mouse or by keyboard, but they’re not so hot when it comes to touch. When you press the top-level “Shop” link in our example for the first time, you are telling it to both open the submenu and follow the link.

There are two possible resolutions here:

1. Prevent the default behavior of top-level links (e.preventDefault()) and script in full WAI-ARIA menu semantics and behavior.
2. Make sure each top-level destination page has a table of contents as an alternative to the submenu.

(1) is unsatisfactory because, as I noted previously, these kinds of semantics and behaviors are not expected in this context, where links are the subject controls. Plus users could no longer navigate to a top-level page, if it exists.

Resolution (2) is more inclusive and robust in that it provides a “fallback” for users of all inputs. But the scare quotes around the fallback term here are quite deliberate because I actually think in-page tables of content are a superior way of providing navigation.

The award winning Government Digital Services team would appear to agree. You may also have seen them on Wikipedia.

Tables of content

Tables of content are navigation for related pages or page sections and should be semantically similar to main site navigation regions, using a <nav> element, a list, and a group labeling mechanism.

<nav aria-labelledby="sections-heading">
  <h2 id="sections-heading">Products</h2>
  <ul>
    <li><a href="/products/dog-costumes">Dog costumes</a></li>
    <li><a href="/products/waffle-irons">Waffle irons</a></li>
    <li><a href="/products/magical-orbs">Magical orbs</a></li>
  </ul>
</nav>
<!-- each section, in order, here -->

Notes

• In this example, we’re imagining that each section is its own page, as it would have been in the dropdown submenu.
• It’s important that each of these “Shop” pages has the same structure, with this “Products” table of content present in the same place. Consistency supports understanding.
• The list groups the items and enumerates them in assistive technology output, such as a screen reader’s synthetic voice
• The <nav> is recursively labeled by the heading using aria-labelledby. This means “products navigation” will be announced in most screen readers upon entering the region by Tab. It also means that “products navigation” will be itemized in screen reader element interfaces, from which users can navigate to regions directly.

All on one page

If you can fit all the sections onto one page without it becoming too long and arduous to scroll, even better. Just link to each section’s hash identifier. For example, href="#waffle-irons" should point to id="waffle-irons".

<nav aria-labelledby="sections-heading">
  <h2 id="sections-heading">Products</h2>
  <ul>
    <li><a href="#dog-costumes">Dog costumes</a></li>
    <li><a href="#waffle-irons">Waffle irons</a></li>
    <li><a href="#magical-orbs">Magical orbs</a></li>
  </ul>
</nav>
<!-- dog costumes section here -->
<section id="waffle-irons" tabindex="-1">
  <h2>Waffle Irons</h2>
</section>
<!-- magical orbs section here -->

(Note: Some browsers are poor at actually sending focus to linked page fragments. Placing tabindex="-1" on the target fragment fixes this.)

Where a site has a lot of content, a carefully constructed information architecture, expressed through the liberal use of tables of content “menus” is infinitely preferable to a precarious and unwieldy dropdown system. Not only is it easier to make responsive, and requires less code to do so, but it makes things clearer: where dropdown systems hide structure away, tables of content lay it bare.

Some sites, including the Government Digital Service’s gov.uk, include index (or “topic”) pages that are just tables of content. It’s such a powerful concept that the popular static site generator Hugo generates such pages by default.

Information architecture is a big part of inclusion. A badly organized site can be as technically compliant as you like, but will still alienate lots of users — especially those with cognitive impairments or those who are pressed for time.

Navigation menu buttons

While we’re on the subject of faux navigation-related menus, it’d be remiss of me not to talk about navigation menu buttons. You’ve almost certainly seen these denoted by a three-line “hamburger” or “navicon” icon.

Even with a pared down information architecture and only one tier of navigation links, space on small screens is at a premium. Hiding navigation behind a button means there’s more room for the main content in the viewport.

A navigation button is the closest thing we’ve studied so far to a true menu button. Since it has the purpose of toggling the availability of a menu on click, it should

1. Identify itself as a button, not a link;
2. Identify the expanded or collapsed state of its corresponding menu (which, in strict terms, is just a list of links).

Progressive enhancement

But let’s not get ahead of ourselves. We ought to be mindful of progressive enhancement and consider how this would work without JavaScript.

In an unenhanced HTML document there’s not a lot you can do with buttons (except submit buttons but that’s not even closely related to what we want to achieve here). Instead, perhaps we should start with just a link which takes us to the navigation?

<a href="#navigation">navigation</a>
<!-- some content here perhaps -->
<nav id="navigation">
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
    <li><a href="/shop">Shop</a></li>
    <li><a href="/content">Content</a></li>
  </ul>
</nav>

There’s not a lot of point in having the link unless there’s a lot of content between the link and the navigation. Since site navigation should almost always appear near the top of the source order, there’s no need. So, really, a navigation menu in the absence of JavaScript should just be… some navigation.

<nav id="navigation">
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
    <li><a href="/shop">Shop</a></li>
    <li><a href="/content">Content</a></li>
  </ul>
</nav>

You enhance this by adding the button, in its initial state, and hiding the navigation (using the hidden attribute):

<nav id="navigation">
  <button aria-expanded="false">Menu</button>
  <ul hidden>
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
    <li><a href="/shop">Shop</a></li>
    <li><a href="/contact">Contact</a></li>
  </ul>
</nav>

Some older browsers — you know which ones — don’t support hidden, so remember to put the following in your CSS. It fixes the problem because display: none has the same affect of hiding the menu from assistive technologies and removing the links from focus order.

[hidden] {
  display: none;
}

Doing one’s best to support older software is, of course, an act of inclusive design. Some are unable or unwilling to upgrade.

Placement

Where a lot of people go wrong is by placing the button outside the region. This would mean screen reader users who move to the <nav> using a shortcut would find it to be empty, which isn’t very helpful. With the list hidden from screen readers, they’d just encounter this:

<nav id="navigation">
</nav>

Here’s how we might toggle state:

var navButton = document.querySelector('nav button');
navButton.addEventListener('click', function() {
  let expanded = this.getAttribute('aria-expanded') === 'true' || false;
  this.setAttribute('aria-expanded', !expanded);
  let menu = this.nextElementSibling;
  menu.hidden = !menu.hidden;
});

aria-controls

As I wrote in Aria-controls Is Poop, the aria-controls attribute, intended to help screen reader users navigate from a controlling element to a controlled element, is only supported in the JAWS screen reader. So you simply can’t rely on it.

Without a good method for directing users between elements, you should instead make sure one of the following is true:

1. The expanded list’s first link is next in focus order after the button (as in the previous code example).
2. The first link is focused programmatically upon revealing the list.

In this case, I would recommend (1). It’s a lot simpler since you don’t have to worry about moving focus back to the button and on which event(s) to do so. Also, there’s currently nothing in place to warn users that their focus will be moved to somewhere different. In the true menus we’ll be discussing shortly, this is the job of aria-haspopup="true".

Employing aria-controls doesn’t really do much harm, except that it makes readout in screen readers more verbose. However, some JAWS users may expect it. Here is how it would be applied, using the list’s id as the cipher:

<nav id="navigation">
  <button aria-expanded="false" aria-controls="menu-list">Menu</button>
  <ul id="menu-list" hidden>
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
    <li><a href="/shop">Shop</a></li>
    <li><a href="/contact">Contact</a></li>
  </ul>
</nav>

The menu and menuitem roles

A true menu (in the WAI-ARIA sense) should identify itself as such using the menu role (for the container) and, typically, menuitem children (other child roles may apply). These parent and child roles work together to provide information to assistive technologies. Here’s how a list might be augmented to have menu semantics:

<ul role="menu">
  <li role="menuitem">Item 1</li>
  <li role="menuitem">Item 2</li>
  <li role="menuitem">Item 3</li>
</ul>

Since our navigation menu is beginning to behave somewhat like a “true” menu, should these not be present?

The short answer is: no. The long answer is: no, because our list items contain links and menuitem elements are not intended to have interactive descendants. That is, they are the controls in a menu.

We could, of course, suppress the list semantics of the <li>s using role="presentation" or role="none" (which are equivalent) and place the menuitem role on each link. However, this would suppress the implicit link role. In other words, the example to follow would be announced as “Home, menu item”, not “Home, link” or “Home, menu item, link”. ARIA roles simply override HTML roles.

<!-- will be read as "Home, menu item" -->
<li role="presentation">
  <a href="/" role="menuitem">Home</a>
</li>

We want the user to know that they are using a link and can expect link behavior, so this is no good. Like I said, true menus are for (JavaScript driven) application behavior.

What we’re left with is a kind of hybrid component, which isn’t quite a true menu but at least tells users whether the list of links is open, thanks to the aria-expanded state. This is a perfectly satisfactory pattern for navigation menus.

True menus

Now that we’ve had the discussion about false menus and quasi-menus, the time has arrived to create a true menu, as opened and closed by a true menu button. From here on in I will refer to the button and menu together as simply a “menu button”.

But in what respects will our menu button be true? Well, it’ll be a menu component intended for choosing options in the subject application, which implements all the expected semantics and corresponding behaviors to be considered conventional for such a tool.

As mentioned already, these conventions come from desktop application design. ARIA attribution and JavaScript governed focus management are needed to imitate them fully. Part of the purpose of ARIA is to help web developers create rich web experiences without breaking with usability conventions forged in the native world.

In this example, we’ll imagine our application is some sort of game or quiz. Our menu button will let the user choose a difficulty level. With all the semantics in place, the menu looks like this:

<button aria-haspopup="true" aria-expanded="false">
  Difficulty
  <span aria-hidden="true">&#x25be;</span>
</button>
<div role="menu">
  <button role="menuitem">Easy</button>
  <button role="menuitem">Medium</button>
  <button role="menuitem">Incredibly Hard</button>
</div>

Notes

• The aria-haspopup property simply indicates that the button secretes a menu. It acts as warning that, when pressed, the user will be moved to the “popup” menu (we’ll cover focus behavior shortly). Its value does not change — it remains as true at all times.
• The <span> inside the button contains the unicode point for a black down-pointing small triangle. This convention indicates visually what aria-haspopup does non-visually — that pressing the button will reveal something below it. The aria-hidden="true" attribution prevents screen readers from announcing “down pointing triangle” or similar. Thanks to aria-haspopup, it’s not needed in the non-visual context.
• The aria-haspopup property is complemented by aria-expanded. This tells the user whether the menu is currently in an open (expanded) or closed (collapsed) state by toggling between true and false values.
• The menu itself takes the (aptly named) menu role. It takes descendants with the menuitem role. They do not need to be direct children of the menu element, but they are in this case — for simplicity.

Keyboard and focus behavior

When it comes to making interactive controls keyboard accessible, the best thing you can do is use the right elements. Because we’re using <button> elements here, we can be assured that click events will fire on Enter and Space keystrokes, as specified in the HTMLButtonElement interface. It also means that we can disable the menu items using the button-associated disabled property.

There’s a lot more to menu button keyboard interaction, though. Here’s a summary of all the focus and keyboard behavior we’re going to implement, based on WAI-ARIA Authoring Practices 1.1:

The advantage of moving focus between menu items using the arrow keys is that Tab is preserved for moving out of the menu. In practice, this means users don’t have to move through every menu item to exit the menu — a huge improvement for usability, especially where there are many menu items.

The application of tabindex="-1" makes the menu items unfocusable by Tab but preserves the ability to focus the elements programmatically, upon capturing key strokes on the arrow keys.

<button aria-haspopup="true" aria-expanded="false">
  Difficulty
  <span aria-hidden="true">&#x25be;</span>
</button>
<div role="menu">
  <button role="menuitem" tabindex="-1">Easy</button>
  <button role="menuitem" tabindex="-1">Medium</button>
  <button role="menuitem" tabindex="-1">Incredibly Hard</button>
</div>

The open method

As part of a sound API design, we can construct methods for handling the various events.

For example, the open method needs to switch the aria-expanded value to “true”, change the menu’s hidden property to false, and focus the first menuitem in the menu that isn’t disabled:

MenuButton.prototype.open = function () {
  this.button.setAttribute('aria-expanded', true);
  this.menu.hidden = false;
  this.menu.querySelector(':not([disabled])').focus();

  return this;
}

We can execute this method where the user presses the down key on a focused menu button instance:

this.button.addEventListener('keydown', function (e) {
  if (e.keyCode === 40) {
    this.open();
  }
}.bind(this));

In addition, a developer using this script will now be able to open the menu programmatically:

exampleMenuButton = new MenuButton(document.querySelector('[aria-haspopup]'));

exampleMenuButton.open();

The “choose” event

Executing some methods should emit events so that we can set up listeners. For example, we can emit a choose event when a user clicks a menu item. We can set this up using CustomEvent, which lets us pass an argument to the event’s detail property. In this case, the argument (“choice”) would be the chosen menu item’s DOM node.

MenuButton.prototype.choose = function (choice) {
  // Define the 'choose' event 
  var chooseEvent = new CustomEvent('choose', {
    detail: {
      choice: choice
    }
  });
  // Dispatch the event
  this.button.dispatchEvent(chooseEvent);

  return this;
}

There are all sorts of things we can do with this mechanism. Perhaps we have a live region set up with an id of menuFeedback:

<div role="alert" id="menuFeedback"></div>

Now we can set up a listener and populate the live region with the information secreted inside the event:

exampleMenuButton.addEventListener('choose', function (e) {
  // Get the node's text content (label)
  var choiceLabel = e.details.choice.textContent;

  // Get the live region node
  var liveRegion = document.getElementById('menuFeedback');

  // Populate the live region
  liveRegion.textContent = `Your difficulty level is  ${choiceLabel}`;
}):

When a menu item is selected, the screen reader user will hear, “You chose [menu item’s label]”. A live region (defined here with the role="alert" attribution) announces its content in screen readers whenever that content changes. The live region isn’t mandatory, but it is an example of what might happen in the interface as a response to the user making a menu choice.

Persisting choices

Not all menu items are for choosing persistent settings. Many just act like standard buttons which make something in the interface happen when pressed. However, in the case of our difficulty menu button, we’d like to indicate which is the current difficulty setting — the one chosen last.

The aria-checked="true" attribute works for items that, instead of menuitem, take the menuitemradio role. The enhanced markup, with the second item checked (set) looks like this:

<button aria-haspopup="true" aria-expanded="false">
  Difficulty
  <span aria-hidden="true">&#x25be;</span>
</button>
<div role="menu">
  <button role="menuitemradio" tabindex="-1">Easy</button>
  <button role="menuitemradio" aria-checked="true"  tabindex="-1">Medium</button>
  <button role="menuitemradio" tabindex="-1">Incredibly Hard</button>
</div>

Native menus on many platforms indicate chosen items using check marks. We can do that with no trouble using a little extra CSS:

[role="menuitem"][aria-checked="true"]::before {
  content: '\2713\0020';
}

While traversing the menu with a screen reader running, focusing this checked item will prompt an announcement like “check mark, Medium menu item, checked”.

The behavior on opening a menu with a checked menuitemradio differs slightly. Instead of focusing the first (enabled) item in the menu, the checked item is focused instead.

What’s the benefit of this behavior? The user (any user) is reminded of their previously selected option. In menus with numerous incremental options (for example, a set of zoom levels), people operating by keyboard are placed in the optimal position to make their adjustment.

Using the menu button with a screen reader

In this video, I’ll show you what it’s like to use the menu button with the Voiceover screen reader and Chrome. The example uses items with menuitemradio, aria-checked and the focus behavior discussed. Similar experiences can be expected across the gamut of popular screen reader software.

Inclusive Menu Button on Github

Hugo Giraudel and I have worked together on creating a menu button component with the API features I have described, and more. You have Hugo to thank for many of these features, since they were based on the work they did on a11y-dialog — an accessible modal dialog. It is available on Github and NPM.

npm i inclusive-menu-button --save

In addition, Hugo has created a React version for your delectation.

Checklist

• Don’t use ARIA menu semantics in navigation menu systems.
• On content heavy sites, don’t hide structure away in nested dropdown-powered navigation menus.
• Use aria-expanded to indicate the open/closed state of a button-activated navigation menu.
• Make sure said navigation menu is next in focus order after the button that opens/closes it.
• Never sacrifice usability in the pursuit of JavaScript-free solutions. It’s vanity.

TodoMVC compares and contrasts todo app implementations of popular MV* frameworks including Vue.js, Angular.js, and Ember.js. As a developer researching technology for a new project, it enables you to find the most intuitive and ergonomic choice for your needs.

The inclusive design of a todo list interface is, however, framework agnostic. Your user doesn’t care if it’s made with Backbone or React; they just need the end product to be accessible and easy to use. Unfortunately, each of the identical implementations in TodoMVC have some shortcomings. Most notably, the delete functionality only appears on hover, making it an entirely inaccessible feature by keyboard.

In this article, I’ll be building an integrated todo list component from the ground up. But what you learn doesn’t have to apply just to todo lists — we’re really exploring how to make the basic creation and deletion of content inclusive.

Unlike the simple, single element toggle buttons of the previous article, managed lists have a few moving parts. This is what we’re going to make:

The heading

A great deal of usability is about labels. The <label> element provides labels to form fields, of course. But simple text nodes provided to buttons and links are also labels: they tell you what those elements do when you press them.

Headings too are labels, giving names to the sections (regions, areas, modules) that make up an interface. Whether you are creating a static document, like a blog post, or an interactive single-page application, each major section in the content of that page should almost certainly be introduced by a heading. Our todo list’s name, “My Todo List” in this case, should be marked up accordingly.

<h1>My Todo List</h1>

It’s a very on the nose way of demarcating an interface, but on the nose is good. We don’t want our users having to do any detective work to know what it is they’re dealing with.

Heading level

Determining the correct level for the heading is often considered a question of importance, but it’s actually a question of belonging. If our todo list is the sole content within the <main> content of the page, it should be level 1, as in the previous example. There’s nothing surrounding it, so it’s at the highest level in terms of depth.

If, instead, the todo list is provided as supplementary content, it should have a level which reflects that. For example, if the page is about planning a holiday, a “Things to pack” todo list may be provided as a supplementary tool.

• Plan for my trip (<h1>)
  • Places to get drunk (<h2>)
    • Bars (<h3>)
    • Clubs (<h3>)
  • Things to pack (todo list) (<h2>)

In the above example, both “Bars” and “Clubs” belong to “Places to get drunk”, which belongs to “Plan for my trip”. That’s three levels of belonging, hence the <h3>s.

Even if you feel that your packing todo list is less important than establishing which bars are good to visit, it’s still on the same level in terms of belonging, so it must have the same heading level.

As well as establishing a good visual hierarchy, the structure described by logically nested sections gives screen reader users a good feel for the page. Headings are also harnessed as navigational tools by screen readers. For example, in JAWS, the 2 key will take you to the next section labeled by an <h2> heading. The generic h key will take you to the next heading of any level.

The list

I talk about the virtues of lists in Inclusive Design Patterns. Alongside headings, lists help to give pages structure. Without headings or lists, pages are featureless and monotonous, making them very difficult to unpick both visually and non-visually.

Not all lists need to be bullet lists, showing a list-style, but there should be some visual indication that the items within the list are similar or equivalent; that they belong together. Non-visually, using the <ul> or <ol> container means the list is identified when encountered and its items are enumerated. For our three-item todo list, screen readers should announce something like, “list of three items”.

A todo list is, as the name suggests, a list. Since our particular todo list component makes no assertions about priority, an unordered list is fine. Here’s the structure for a static version of our todo list (the adding, deleting, and checking functionality has not yet been added):

<section aria-labelledby="todos-label">
  <h1 id="todos-label">My Todo List</h1>
  <ul>
    <li>
      Pick up kids from school
    </li>
    <li>
      Learn Haskell
    </li>
    <li>
      Sleep
    </li>
  </ul>
</section>

Empty state

Empty states are an aspect of UI design which you neglect at your peril. Inclusive design has to take user lifecycles into consideration, and some of your most vulnerable users are new ones. To them your interface is unfamiliar and, without carefully leading them by the hand, that unfamiliarity can be off-putting.

With our heading and “add” input present it may be obvious to some how to proceed, even without example todo items or instructions present. But your interface may be less familiar and more complex than this simple todo list, so let’s add an empty state anyway — for practice.

Revealing the empty state

It’s quite possible, of course, to use our data to determine whether the empty state should be present. In Vue.js, we might use a v-if block:

<div class="empty-state" v-if="!todos.length">
  <p>Either you've done everything already or there are still things to add to your list. Add your first todo &#x2193;</p>
</div>

But all the state information we need is actually already in the DOM, meaning all we need in order to switch between showing the list and showing the empty-state is CSS.

.empty-state, ul:empty {
  display: none;
}

ul:empty + .empty-state {
  display: block;
}

This is more efficient because we don’t have to query the data or change the markup. It’s also screen reader accessible: display: none makes sure the element in question is hidden both visually and from screen reader software.

All pseudo-classes pertain to implicit states. The :empty pseudo-class means the element is in an empty state; :checked means it’s in a checked state; :first-child means it’s positioned at the start of a set. The more you leverage these, the less DOM manipulation is required to add and change state with JavaScript.

Adding a todo item

We’ve come this far without discussing the adding of todos. Let’s do that now. Beneath the list (or empty state if the list is empty) is a text input and “add” button:

Form or no form?

It’s quite valid in HTML to provide an <input> control outside of a <form> element. The <input> will not succeed in providing data to the server without the help of JavaScript, but that’s not a problem in an application using XHR.

But do <form> elements provide anything to users? When users of screen readers like JAWS or NVDA encounter a <form> element, they are automatically entered into a special interaction mode variously called “forms mode” or “application mode”. In this mode, some keystrokes that would otherwise be used as special shortcuts are switched off, allowing the user to interact with the form fields fully.

Fortunately, most input types — including type="text" here — trigger forms mode themselves, on focus. For instance, if I were to type h in the pictured input, it would enter “h” into the field, rather than navigating me to the nearest heading element.

The real reason we need a <form> element is because we’ll want to allow users to submit on Enter, and this only works reliably where a <form> contains the input upon which Enter is being pressed. The presence of the <form> is not just for code organization, or semantics, but affects browser behavior.

<form>
  <input type="text" placeholder="E.g. Adopt an owl">
  <button type="submit">Add</button>
</form>

(Note: Léonie Watson reports that range inputs are non-functional in Firefox + JAWS unless a <form> is employed or forms mode is entered manually, by the user.)

Labeling

Can you spot the deliberate mistake in the above code snippet? The answer is: I haven’t provided a label. Only a placeholder is provided and placeholders are intended for supplementary information only, such as the “adopt an owl” suggestion.

Placeholders are not reliable as labeling methods in assistive technologies, so another method must be provided. The question is: should that label be visible, or only accessible by screen reader?

In almost all cases, a visible label should be placed above or to the left of the input. Part of the reason for this is that placeholders disappear on focus and can be eradicated by autocomplete behavior, meaning sighted users lose their labels. Filling out information or correcting autocompleted information becomes guesswork.

However, ours is a bit of a special case because the “add” label for the adjacent button is quite sufficient. Those looking at the form know what the input does thanks to the button alone.

All inputs should have labels, because screen reader users don’t know to look ahead in the source to see if the submit button they’ve yet to reach gives them any clues about the form’s purpose. But simple input/submit button pairs like this and search regions can get away without visible labels. That is, so long as the submit button’s label is sufficiently descriptive.

There are a number of ways to provide an invisible label to the input for screen reader users. One of the simpler and least verbose is aria-label. In the following example, “Write a new todo item” is the value. It’s a bit more descriptive than just “add”, which also helps to differentiate it from the button label, avoiding confusion when focus is moved between the two elements.

<form>
  <input type="text" aria-label="Write a new todo item" placeholder="E.g. Adopt an owl">
  <button type="submit">Add</button>
</form>

Submission behavior

One of the advantages of using a <form> with a button of the submit type is that the user can submit by pressing the button directly, or by hitting Enter. Even users who do not rely exclusively on the keyboard to operate the interface may like to hit Enter because it’s quicker. What makes interaction possible for some, makes it better for others. That’s inclusion.

If the user tries to submit an invalid entry we need to stop them. By disabling the <button> until the input is valid, submission by click or by Enter is suppressed. In fact, the type="submit" button stops being focusable by keyboard. In addition to disabling the button, we provide aria-invalid="true" to the input. Screen readers will tell their users the input is invalid, letting them know they need to change it.

<form>
  <input type="text" aria-invalid="true" aria-label="Write a new todo item" placeholder="E.g. Adopt an owl">
  <button type="submit" disabled>Add</button>
</form>

Feedback

The deal with human-computer interaction is that when one party does something, the other party should respond. It’s only polite. For most users, the response on the part of the computer to adding an item is implicit: they simply see the item being added to the page. If it’s possible to animate the appearance of the new item, all the better: Some movement means its arrival is less likely to be missed.

For users who are not sighted or are not using the interface visually, nothing would seem to happen. They remain focused on the input, which offers nothing new to be announced in screen reader software. Silence.

Moving focus to another part of the page — the newly added todo, say — would cause that element to be announced. But we don’t want to move the user’s focus because they might want to forge ahead writing more todos. Instead we can use a live region.

The feedback live region

Live regions are elements that tell screen readers to announce their contents whenever those contents change. With a live region, we can make screen readers talk to their users without making those users perform any action (such as moving focus).

Basic live regions are defined by role="status" or the equivalent aria-live="polite". To maximize compatibility with different screen readers, you should use both. It may feel redundant, but it increases your audience.

<div role="status" aria-live="polite">
  <!-- add content to hear it spoken -->
</div>

On the submit event, I can simply append the feedback to the live region and it will be immediately announced to the screen reader user.

var todoName = document.querySelector('[type="text"]').value;

function addedFeedback(todoName) {
  let liveRegion = document.querySelector('[role="status"]');
  liveRegion.textContent = `${todoName} added.`;
}

// example usage
addedFeedback(todoName);

One of the simplest ways to make your web application more accessible is to wrap your status messages in a live region. Then, when they appear visually, they are also announced to screen reader users.

Inclusion is all about different users getting an equivalent experience, not necessarily the same experience. Sometimes what works for one user is meaningless, redundant, or obstructive to another.

In this case, the status message is not really needed visually because the item can be seen joining the list. In fact, adding the item to the list and revealing a status message at the same time would be to pull the user’s attention in two directions. In other words: the visible appending of the item and the announcement of “[item name] added” are already equivalent.

In which case, we can hide this particular messaging system from view, with a vh (visually hidden) class.

<div role="status" aria-live="polite" class="vh">
  <!-- add content to hear it spoken -->
</div>

This utility class uses some magic to make sure the element(s) in question are not visible or have layout, but are still detected and announced in screen readers. Here’s what it looks like:

.vh {
    position: absolute !important;
    clip: rect(1px, 1px, 1px, 1px);
    padding:0 !important;
    border:0 !important;
    height: 1px !important;
    width: 1px !important;
    overflow: hidden;
}

Checking off todo items

Unlike in the previous toggle button post, this time checkboxes feel like the semantically correct way to activate and deactivate. You don’t press or switch off todo items; you check them off.

Lucky, checkboxes let us do that with ease — the behavior comes out-of-the-box. We just need to remember to label each instance. When iterating over the checkbox data, we can write unique values to each for/id pairing using a for loop’s current index and string interpolation. Here’s how it can be done in Vue.js:

<ul>
  <li v-for="(todo, index) in todos">
    <input type="checkbox" :id="`todo-${index}`" v-model="todo.done"> 
    <label :for="`todo-${index}`">{{todo.name}}</label>     
  </li>
</ul>

(Note: In this example, we imagine that each todo has a done property, hence v-model="todo.done" which automatically checks the checkbox where it evaluates as true.)

The line-through style

Making robust and accessible components is easy when you use semantic elements as they were intended. In my version, I just add a minor enhancement: a line-through style for checked items. This is applied to the <label> via the :checked state using an adjacent sibling combinator.

:checked + label {
  text-decoration: line-through;
}

Once again, I’m leveraging implicit state to affect style. No need for adding and removing class="crossed-out" or similar.

(Note: If you want to style the checkbox controls themselves, WTF Forms gives guidance on doing so without having to create custom elements. In the demo at the end of this article, I use a proxy .tick <span> to do something similar.)

Deleting todo items

Checking off and deleting todo list items are distinct actions. Because sometimes you want to see which items you’ve done, and sometimes you add todo items to your list that you didn’t mean to, or which become non-applicable.

The functionality to delete todos can be provided via a simple button. No need for any special state information — the label tells us everything we need to know. Of course, if the button uses an icon image or font glyph in place of an interpretable text node, an auxiliary label should be provided.

<button aria-label="delete">
  &times;
</button>

In fact, let’s be more specific and include the todo item’s name. It’s always better to provide labels which make sense in isolation. This unique label helps differentiate it from the others. Your JavaScript framework of choice should provide a templating facility to achieve this. In my choice, Vue.js, it looks like this:

<button :aria-label="`delete ${todo.name}`">
  &times;
</button>

In this example, × is used to represent a cross symbol. Were it not for the aria-label overriding it, the label would be announced as “times” or “multiplication” depending on the screen reader in question.

Always be wary of how screen readers interpret special unicode characters and symbols. Sometimes, arguably, they are quite helpful, like the down arrow in our empty state message. This will be interpreted as “down pointing arrow” or similar. Since, in our case, the text input is always below the list both visually and in source order, the arrow guides the user toward it.

In our case, a dustbin icon is provided using SVG. SVG is great because it’s an image format that scales without degrading. Many kinds of users often feel the need to scale/zoom interfaces, including the short-sighted and those with motor impairments who are looking to create larger touch or click targets.

<button aria-label="delete">
  <svg>
    <use xlink:href="#bin-icon"></use>
  </svg>
</button>

To reduce bloat when using multiple instances of the same inline SVG icon, we employ the <use> element, which refers to a canonical version of the SVG, defined as a <symbol> at the head of the document body:

<body>
  <svg style="display: none">
    <symbol id="bin-icon" viewBox="0 0 20 20">
      <path d="[path data here]">
    </symbol>
  </svg>

A bloated DOM can diminish the experience of many users since many operations will take longer. Assistive technology users especially may find their software unresponsive.

Focus management

When a user clicks the delete button for a todo item, the todo item — including the checkbox, the label, and the delete button itself — will be remove from the DOM. This raises an interesting problem: what happens to focus when you delete the currently focused element?

Unless you’re careful, the answer is something very annoying for keyboard users, including screen reader users.

The truth is, browsers don’t know where to place focus when it has been destroyed in this way. Some maintain a sort of “ghost” focus where the item used to exist, while others jump to focus the next focusable element. Some flip out completely and default to focusing the outer document — meaning keyboard users have to crawl through the DOM back to where the removed element was.

For a consistent experience between users, we need to be deliberate and focus() an appropriate element, but which one?

One option is to focus the first checkbox of the list. Not only will this announce the checkbox’s label and state, but also the total number of list items remaining: one fewer than a moment ago. All useful context.

document.querySelector('ul input').focus();

(Note: querySelector returns the first element that matches the selector. In our case: the first checkbox in the todo list.)

But what if we just deleted the last todo item in our list and had returned to the empty state? There’s no checkbox we can focus. Let’s try something else. Instead, I want to do two things:

1. Focus the region’s “My Todo List” heading
2. Use the live region already instated to provide some feedback

You should never make non-interactive elements like headings focusable by users because the expectation is that, if they’re focusable, they should actually do something. When I’m testing an interface and there are such elements, I would therefore fail it under WCAG 2.4.3 Focus Order.

However, sometimes you need to direct a user to a certain part of the page, via a script. In order to move a user to a heading and have it announced, you need to do two things:

1. Provide that heading with tabindex="-1"
2. Focus it using the focus() method in your script

<h1 tabindex="-1">My Todo List</h1>

The -1 value’s purpose is twofold: it makes elements unfocusable by users (including normally focusable elements) but makes them focusable by JavaScript. In practice, we can move a user to an inert element without it becoming a “tab stop” (an element that can be moved to via the Tab key) among focusable elements within the page.

In addition, focusing the heading will announce its text, role, level, and (in some screen readers) contextual information such as “region”. At the very least, you should hear “My Todo List, heading, level 2”. Because it is in focus, pressing tab will step the user back inside the list and onto the first checkbox. In effect, we’re saying, “now that you’ve deleted that list item, here’s the list again.”

I typically do not supply focus styles to elements which are focused programmatically in this way. Again, this is because the target element is not interactive and should not appear to be so.

[tabindex="-1"] { outline: none }

After the focused element (and with it its focus style) has been removed, the heading is focused. A keyboard user can then press Tab to find themselves on that first checkbox or — if there are no items remaining — the text input at the foot of the component.

The feedback

Arguably, we’ve provided enough information for the user and placed them in a perfect position to continue. But it’s always better to be explicit. Since we already have a live region instated, why not use that to tell them the item has been successfully removed?

function deletedFeedback(todoName) {
  let liveRegion = document.querySelector('[role="status"]');
  liveRegion.textContent = `${todoName} deleted.`;
}

// example usage
deletedFeedback(todoName);

I appreciate that you probably wouldn’t be writing this in vanilla JavaScript, but this is basically how it would work.

Now, because we’ve used role="status" (aria-live="polite"), something neat happens in supporting screen readers: “My Todo List, heading, level 2” is read first, followed by “[todo item name] deleted”.

That’s because polite live regions wait until the interface and the user have settled before making themselves known. Had I used role="alert" (aria-live="assertive"), the status message would override (or partially override) the focus-invoked heading announcement. Instead, the user knows both where they are, and that what they’ve tried to do has succeeded.

Working demo

I’ve created a codePen page to demonstrate the techniques in this post. It uses Vue.js, but could have been created with any JavaScript framework. It’s offered for testing with different screen reader and browser combinations.

Conclusion

Counting semantic structure, labeling, iconography, focus management and feedback, there’s quite a lot to consider when creating an inclusive todo list component. If that makes inclusive design seem dauntingly complex, consider the following:

1. This is new stuff. Don’t worry, it’ll become second nature soon enough.
2. Everything you’ve learned here is applicable to a wide range of content management components, and many other components.
3. You only need to build a rock solid component once. Then it can live in your pattern library and be reused indefinitely.

Checklist

• Give every major component, like this one, a well-written heading.
• Only provide “screen reader only” input labels if something else labels the input visually. Placeholders don’t count.
• When you remove a focused element from the DOM, focus an appropriate nearby element with focus().
• Consider the wording of empty states carefully. They introduce new users to your functionality.

In this inaugural post, I’ll be exploring what it takes to make toggle buttons inclusive. As with any component, there’s no one way to go about this, especially when such controls are examined under different contexts. However, there’s certainly plenty to forget to do or to otherwise screw up, so let’s try to avoid any of that.

Changing state

If a web application did not change according to the instructions of its user, the resulting experience would be altogether unsatisfactory. Nevertheless, the luxury of being able to make web documents augment themselves instantaneously, without recourse to a page refresh, has not always been present.

Unfortunately, somewhere along the way we decided that accessible web pages were only those where very little happened — static documents, designed purely to be read. Accordingly, we made little effort to make the richer, stateful experiences of web applications inclusive.

A popular misconception has been that screen readers don’t understand JavaScript. Not only is this entirely untrue — all major screen readers react to changes in the DOM as they occur — but basic state changes, communicated both visually and to assistive technology software, do not necessarily depend on JavaScript to take place anyway.

Checkboxes and radio buttons

Form elements are the primitives of interactive web pages and, where we’re not employing them directly, we should be paying close attention to how they behave. Their handling of state changes have established usability conventions we would be foolish to ignore.

Arguably, an out-of-the-box input of the checkbox type is a perfectly serviceable on/off switch all its own. Where labelled correctly, it has all the fundamental ingredients of an accessible control: it’s screen reader and keyboard accessible between platforms and devices, and it communicates its change of state (checked to unchecked or vice versa) without needing to rebuild the entire document.

In the following example, a checkbox serves as the toggle for an email notifications setting.

<input type="checkbox" id="notify" name="notify" value="on">  
<label for="notify">Notify by email</label>  

Screen reader software is fairly uniform in its interpretation of this control. On focusing the control (moving to it using the Tab key) something similar to, “Notify by email, checkbox, unchecked” will be announced. That’s the label, role, and state information all present.

On checking the checkbox, most screen reader software will announce the changed state, “checked” (sometimes repeating the label and role information too), immediately. Without JavaScript, we’ve handled state and screen reader software is able to feed back to the user.

In this case, the on/off part of the switch is not communicated by the label but the state. Instead, the label is for identifying the thing that we are turning off or on. Should research show that users benefit from a more explicit on/off metaphor, a radio button group can be employed.

<fieldset>  
  <legend>Notify by email</legend>
  <input type="radio" id="notify-on" name="notify" value="on" checked>
  <label for="notify-on">on</label>
  <input type="radio" id="notify-off" name="notify" value="off">
  <label for="notify-off">off</label>
</fieldset>  

Group labels are a powerful tool. As their name suggests, they can provide a single label to related (grouped) items. In this case, the <fieldset> group element works together with the <legend> element to provide the group label “Notify by email” to the pair of radio buttons. These buttons are made a pair by sharing a name attribute value, which makes it possible to toggle between them using your arrow keys. HTML semantics don’t just add information but also affect behavior.

In the Windows screen readers JAWS and NVDA, when the user focuses the first control, the group label is prepended to that control’s individual label and the grouped radio buttons are enumerated. In NVDA, the term “grouping” is appended to make things more explicit. In the above example, focusing the first (checked by default) radio button elicits, “Notify by email, grouping, on radio button, checked, one of two”.

Now, even though the checked state (announced as “selected” in some screen readers) is still being toggled, what we’re really allowing the user to do it switch between “on” and “off”. Those are the two possible lexical states, if you will, for the composite control.

This doesn’t quite feel right

Both the checkbox and radio button implementations are tenable as on/off controls. They are, after all, accessible by mouse, touch, keyboard, and assistive technology software across different devices, browsers, and operating systems.

But accessibility is only a part of inclusive design. These controls also have to make sense to users; they have to play an unambiguous role within the interface.

The trouble with using form elements is their longstanding association with the collection of data. That is, checkboxes and radio buttons are established as controls for designating values. When a user checks a checkbox, they may just be switching a state, but they may suspect they are also choosing a value for submission.

Whether you’re a sighted user looking at a checkbox, a screen reader user listening to its identity being announced, or both, its etymology is problematic. We expect toggle buttons to be buttons, but checkboxes and radio buttons are really inputs.

A true toggle button

Sometimes we use <button> elements to submit forms. To be fully compliant and reliable these buttons should take the type value of submit.

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

But these are only one variety of button, covering one use case. In truth, <button> elements can be used for all sorts of things, and not just in association with forms. They’re just buttons. We remind ourselves of this by giving them the type value of button.

<button type="button">Send</button>  

The generic button is your go-to element for changing anything within the interface (using JavaScript and without reloading the page) except one’s location within and between documents, which is the purview of links.

Next to links, buttons should be the interactive element you use most prolifically in web applications. They come prepackaged with the “button” role and are keyboard and screen reader accessible by default. Unlike some form elements, they are also trivial to style.

So how do we make a <button> a toggle button? It’s a case of using WAI-ARIA as a progressive enhancement. WAI-ARIA offers states that are not available in basic HTML, such as the pressed state. Imagine a power switch for a computer. When it’s pressed — or pushed in — that denotes the computer is in its “on” state. When it’s unpressed — poking out — the computer must be off.

<button type="button" aria-pressed="true">  
  Notify by email
</button>  

WAI-ARIA state attributes like aria-pressed behave like booleans but, unlike standard HTML state attributes like checked they must have an explicit value of true or false. Just adding aria-pressed is not reliable. Also, the absence of the attribute would mean the unpressed state would not be communicated (a button without the attribute is just a generic button).

You can use this control inside a form, or outside, depending on your needs. But if you do use it inside a form, the type="button" part is important. If it’s not there, some browsers will default to an implicit type="submit" and try to submit the form. You don’t have to use event.preventDefault() on type="button" controls to suppress form submission.

Switching the state from true (on) to false (off) can be done via a simple click handler. Since we are using a <button>, this event type can be triggered with a mouse click, a press of either the Space or Enter keys, or by tapping the button through a touch screen. Being responsive to each of these actions is something built into <button> elements as standard. If you consult the HTMLButtonElement interface, you’ll see that other properties, such as disabled, are also supported out-of-the-box. Where <button> elements are not used, these behaviors have to be emulated with bespoke scripting.

const toggle = document.querySelector('[aria-pressed]');

toggle.addEventListener('click', (e) => {  
  let pressed = e.target.getAttribute('aria-pressed') === 'true';
  e.target.setAttribute('aria-pressed', String(!pressed));
});

A clearer state

An interesting thing happens when a button with the aria-pressed state is encountered by some screen readers: it is identified as a “toggle button” or, in some cases, “push button”. The presence of the state attribute changes the button’s identity.

When focusing the example button with aria-pressed="true" using NVDA, the screen reader announces, “Notify by email, toggle button, pressed”. The “pressed” state is more apt than “checked”, plus we eschew the form data input connotations. When the button is clicked, immediate feedback is offered in the form of “not pressed”.

Styling

The HTML we construct is an important part of the design work we do and the things we create for the web. I’m a strong believer in doing HTML First Prototyping™, making sure there’s a solid foundation for the styled and branded product.

In the case of our toggle button, this foundation includes the semantics and behavior to make the button interoperable with various input (e.g. voice activation software) and output (e.g. screen reader) devices. That’s possible using HTML, but CSS is needed to make the control understandable visually.

Form should follow function, which is simple to achieve in CSS: everything in our HTML that makes our simple toggle button function can also be used to give it form.

• <button> → button element selector
• aria-pressed="true" → [aria-pressed="true"] attribute selector

In a consistent and, therefore, easy to understand interface, buttons should share a certain look. Buttons should all look like buttons. So, our basic toggle button styles should probably inherit from the button element block:

/* For example... */
button {  
  color: white;
  background-color: #000;
  border-radius: 0.5rem;
  padding: 1em 2em;
}

There are a number of ways we could visually denote “pressed”. Interpreted literally, we might make the button look pressed in using some inset box-shadow. Let’s employ an attribute selector for this:

[aria-pressed="true"] {
  box-shadow: inset 0 0 0 0.15rem #000, 
              inset 0.25em 0.25em 0 #fff;
}

To complete the pressed/unpressed metaphor, we can use some positioning and box-shadow to make the unpressed button “poke out”. This block should appear above the [aria-prressed="true"] block in the cascade.

[aria-pressed] {
  position: relative;
  top: -0.25rem;
  left: -0.25rem;
  box-shadow: 0.125em 0.125em 0 #fff, 
              0.25em 0.25em #000;
}

(Note: This styling method is offered just as one idea. You may find that something more explicit, like the use of "on"/"off" labels in an example to follow, is better understood by more users.)

Focus styles

It’s important buttons, along with all interactive components, have focus styles. Otherwise people navigating by keyboard cannot see which element is in their control and ready to be operated.

The best focus styles do not affect layout (the interface shouldn’t jiggle around distractingly when moving between elements). Typically, one would use outline, but outline only ever draws a box in most browsers. To fit a focus style around the curved corners of our button, a box-shadow is better. Since we are using box-shadow already, we have to be a bit careful: note the two comma-separated box-shadow styles in the pressed-and-also-focused state.

/* Remove the default outline and 
add the outset shadow */  
[aria-pressed]:focus {
  outline: none;
  box-shadow: 0 0 0 0.25rem yellow;
}

/* Make sure both the inset and 
outset shadow are present */  
[aria-pressed="true"]:focus {
  box-shadow: 0 0 0 0.25rem yellow,
              inset 0 0 0 0.15rem #000, 
              inset 0.25em 0.25em 0 #fff;  
}

Changing labels

The previous toggle button design has a self-contained, unique label and differentiates between its two states using a change in attribution which elicits a style. What if we wanted to create a button that changes its label from “on” to “off” or “play” to “pause”?

It’s perfectly easy to do this in JavaScript, but there are a couple of things we need to be careful about.

1. If the label changes, what happens with the state?
2. If the label is just “on” or “off” (“play” or “pause”; “active” or “inactive”) how do we know what the button actually controls?

In the previous toggle button example, the label described what would be on or off. Where the “what” part is not consistent, confusion quickly ensues: once “off”/unpressed has become “on”/pressed, I have to unpress the “on” button to turn the “off” button back on. What?

As a rule of thumb, you should never change pressed state and label together. If the label changes, the button has already changed state in a sense, just not via explicit WAI-ARIA state management.

In the following example, just the label changes.

const button = document.querySelector('button');

button.addEventListener('click', (e) => {  
  let text = e.target.textContent === 'Play' ? 'Pause' : 'Play';
  e.target.textContent = text;
});

The problem with this method is that the label change is not announced as it happens. That is, when you click the play button, feedback equivalent to “pressed” is absent. Instead, you have to unfocus and refocus the button manually to hear that it has changed. Not an issue for sighted users, but less ergonomic for blind screen reader users.

Play/pause buttons usually switch between a play symbol (a triangle on its side) and a pause symbol (two vertical lines). We could do this while keeping a consistent non-visual label and changing state.

<!-- Paused state -->  
<button type="button" aria-pressed="false" aria-label="play">  
  &#x25b6;
</button>

<-- Playing state -->  
<button type="button" aria-pressed="true" aria-label="play">  
  &#x23f8;
</button>  

Because aria-label overrides the unicode symbol text node, the paused button is announced as something similar to, “Play button, not pressed” and the playing button as ,“Play button, pressed”.

This works pretty well, except for where voice recognition and activation is concerned. In voice recognition software, you typically need to identify buttons by vocalizing their labels. And if a user sees a pause symbol, their first inclination is to say “pause”, not “play”. For this reason, switching the label rather than the state is more robust here.

Auxiliary labeling

In some circumstances, we may want to provide on/off switches which actually read “on/off”. The trick with these is making sure there is a clear association between each toggle switch and a respective, auxiliary label.

Imagine the email notification setting is grouped alongside other similar settings in a list. Each list item contains a description of the setting followed by an on/off switch. The on/off switch uses the terms “on” and “off” as part of its design. Some <span> elements are provided for styling.

<h2>Notifications</h2>  
<ul>  
  <li>
    Notify by email 
    <button>
      <span>on</span>
      <span>off</span>
    </button>
  </li>
  <li>
    Notify by SMS 
    <button>
      <span>on</span>
      <span>off</span>
    </button>
  </li>
  <li>
    Notify by fax 
    <button>
      <span>on</span>
      <span>off</span>
    </button>
  </li>
  <li>
    Notify by smoke signal 
    <button>
      <span>on</span>
      <span>off</span>
    </button>
  </li>
</ul>  

The virtue of lists is that, both visually and non-visually, they group items together, showing they are related. Not only does this help comprehension, but lists also provide navigational shortcuts in some screen readers. For example, JAWS provides the L (list) and I (list item) quick keys for moving between and through lists.

Each ‘label’ and button is associated by belonging to a common list item. However, not providing an explicit, unique label is dangerous territory — especially where voice recognition is concerned. Using aria-labelledby, we can associate each button with the list’s text:

<h2>Notifications</h2>  
<ul>  
  <li>
    <span id="notify-email">Notify by email</span> 
    <button aria-labelledby="notify-email">
      <span>on</span>
      <span>off</span>
    </button>
  </li>
  <li>
    <span id="notify-sms">Notify by SMS</span>
    <button aria-labelledby="notify-sms">
      <span>on</span>
      <span>off</span>
    </button>
  </li>
  <li>
    <span id="notify-fax">Notify by fax</span>
    <button aria-labelledby="notify-fax">
      <span>on</span>
      <span>off</span>
    </button>
  </li>
  <li>
    <span id="notify-smoke">Notify by smoke signal</span> 
    <button aria-labelledby="notify-smoke">
      <span>on</span>
      <span>off</span>
    </button>
  </li>
</ul>  

Each aria-labelledby value matches the appropriate span id, forming the association and giving the button its unique label. It works much like a <label> element’s for attribute identifying a field’s id.

The switch role

Importantly, the ARIA label overrides each button’s textual content, meaning we can once again employ aria-pressed to communicate state. However, since these buttons are explicitly “on/off” switches, we can instead use the WAI-ARIA switch role, which communicates state via aria-checked.

<h2>Notifications</h2>  
<ul>  
  <li>
    <span id="notify-email">Notify by email</span> 
    <button role="switch" aria-checked="true" aria-labelledby="notify-email">
      <span>on</span>
      <span>off</span>
    </button>
  </li>
  <li>
    <span id="notify-sms">Notify by SMS</span>
    <button role="switch" aria-checked="true" aria-labelledby="notify-sms">
      <span>on</span>
      <span>off</span>
    </button>
  </li>
  <li>
    <span id="notify-fax">Notify by fax</span>
    <button role="switch" aria-checked="false" aria-labelledby="notify-fax">
      <span>on</span>
      <span>off</span>
    </button>
  </li>
  <li>
    <span id="notify-smoke">Notify by smoke signal</span> 
    <button role="switch" aria-checked="false" aria-labelledby="notify-smoke">
      <span>on</span>
      <span>off</span>
    </button>
  </li>
</ul>  

How you would style the active state is quite up to you, but I’d personally save on writing class attributes to the <span>s with JavaScript. Instead, I’d write some CSS using pseudo classes to target the relevant span dependent on the state.

[role="switch"][aria-checked="true"] :first-child, 
[role="switch"][aria-checked="false"] :last-child {
  background: #000;
  color: #fff;
}

Traversing the settings

Now let’s talk about navigating through this settings section using two different strategies: by Tab key (jumping between focusable elements only) and browsing by screen reader (moving through each element).

Even when navigating by Tab key, it’s not only the identity and state of the interactive elements you are focusing that will be announced in screen readers. For example, when you focus the first <button>, you’ll hear that it is a switch with the label “Notify by email”, in its on state. “Switch” is the role and aria-checked="true" is vocalized as “on” where this role is present.

But in most screen readers you’ll also be told you’ve entered a list of four items and that you’re on the first item — useful contextual information that works a bit like the group labelling I covered earlier in this post.

Importantly, because we have used aria-labelledby to associate the adjacent text to the button as its label, that is also available when navigating in this mode.

When browsing from item to item (for example, by pressing the down key when the NVDA screen reader is running), everything you encounter is announced, including the heading (“Notifications, heading level two”). Of course, browsing in this fashion, “Notify by email” is announced on its own as well as in association with the adjacent button. This is somewhat repetitive, but makes sense: “Here’s the setting name, and here’s the on/off switch for the setting of this name.”

How explicitly you need to associate controls to the things they control is a finer point of UX design and worth considering. In this case we’ve preserved our classic on/off switches for sighted users, without confusing or misleading either blind or sighted screen reader users no matter which keyboard interaction mode they are using. It’s pretty robust.

Conclusion

How you design and implement your toggle buttons is quite up to you, but I hope you’ll remember this post when it comes to adding this particular component to your pattern library. There’s no reason why toggle buttons — or any interface component for that matter — should marginalize the number of people they often do.

You can take the basics explored here and add all sorts of design nuances, including animation. It’s just important to lay a solid foundation first.

Checklist

• Use form elements such as checkboxes for on/off toggles if you are certain the user won’t believe they are for submitting data.
• Use <button> elements, not links, with aria-pressed or aria-checked.
• Don’t change label and state together.
• When using visual “on” and “off” text labels (or similar) you can override these with a unique label via aria-labelledby.
• Be careful to make sure the contrast level between the button’s text and background color meets WCAG 2.0 requirements.