Expand and collapse accessibility on the Ind.ie manifesto

TL; DR: Using WAI-ARIA aria-controls, aria-expanded and aria-hidden attributes can make expanding and collapsing content more accessible.

We’re always trying to iterate and improve the accessibility on the Ind.ie site. I’ve recently been updating my knowledge on WAI-ARIA, and I realised I could improve the experience for keyboard navigation and screen reader users on the Ind.ie manifesto.

Expanding and collapsing content boxes are a very common space-saver on modern sites. Usually you’d select the heading of the box to expand and collapse the text underneath. Great if you’re equipped with a mouse and can see what you’re doing. If not, the hidden text will remain hidden away forever.

On the manifesto page, we hide and show longer descriptions of terminology used in the manifesto. Previously we used <dfn> definition tags to mark up the initial text, and <div> to mark up the description. We used the data-definition-text-id='definition-corporate-surveillance' custom data attribute on the <dfn> to programmatically connect the text and description. The key word being *programmatically*. Whilst the custom data attribute gave us a semantic hook for the JavaScript, it meant nothing to someone reading the text with a screen reader, and/or using keyboard navigation.

Improvement needed

In order to improve the accessibility of the page, I needed to cover a few areas:

Progressively enhance the definitions and descriptions so they’re easy to use without JavaScript

We’re fans of progressive enhancement here, and accessibility begins with being able to use the page if JavaScript hasn’t loaded. With such simple content, there are no excuses.

Without the JavaScript expanding and collapsing the content, there’s not many ways to show that the definition and description are connected. I decided that the most meaningful way to do it was through an internal link which linked the definition to the description. Following on from my blog post on skip links a few weeks ago, I knew that I needed to use tabindex='-1' to make the skip link content accessible to keyboard navigation and screen readers.

HTML for basic definitions
<dfn data-definition-text-id='definition-corporate-surveillance'>
	<a class='definition-link' href='#definition-corporate-surveillance'>corporate surveillance</a>
</dfn>

HTML for basic descriptions
<div class='full-text definition-expanded' id='definition-corporate-surveillance' tabindex='-1'>
	<p>Corporate surveillance treats[…]</p>
</div>

Turn the definition links into buttons

When the JavaScript to expand and collapse the content gets added, the link becomes an element that triggers an event. The very definition of a <button>. So my JavaScript first turns the definition and its internal link into a button. This gives us all the accessibility behaviour associated with a button, like being able to use the enter key for interaction.

Connect the definitions to the descriptive text in a way that’s meaningful to screen readers

I learned about the aria-controls attribute from Heydon Pickering’s fantastic blog post on Practical ARIA examples. The attribute helps describe how one element controls another. Teamed with the aria-expanded attribute on the definition, I could describe whether the description was expanded or collapsed. VoiceOver on Safari reads the definition as “corporate surveillance, collapsed, button.”

Add the aria-hidden attribute on to the description, and rather than just hiding the content using the latest CSS hack, the markup can tell assistive technology that it’s hidden.

Definition text HTML after JS has loaded
<button data-definition-text-id="definition-corporate-surveillance" class="definition-link" aria-expanded="true" aria-controls="definition-corporate-surveillance">corporate surveillance</button>

Heydon’s post has a nifty jQuery example for implementing the JavaScript for accessible expanding and collapsing content, however, as we’re using vanilla JavaScript on the Ind.ie site, I had to write it myself.

Toggle the expanding and collapsing of the content

Once I knew the HTML was going to be as accessible as possible, I could then use JavaScript to toggle the visibility of the content using CSS. You can see the script in its entirety on the Ind.ie Source repository. Be kind, I’m still getting my head around JS!

Not too tricky

The hardest part for me was writing the JavaScript, as I’m still learning. Hopefully you can see from this post that just a little more love and attention to the HTML, and your expanding and collapsing content can be a lot more accessible.