How to Build an Accessible Accordion in Drupal

Custom widgets have become a staple of websites today. From simple menu toggles to fancy interactive charts, custom functionality can help condense and improve layouts, increase visual interest, and create fun interactive experiences for users. Unfortunately, these same custom widgets are often unwittingly the biggest culprit for accessibility errors, rendering content mysteriously convoluted or in some cases completely hidden to users of assistive technology. Luckily, with the right structure and attributes, custom widgets can be exposed for interactive control by assistive technology, and even improve the user experience for users.

Today we’re going to walk through a very common widget: the accordion. Accordions are often used to help reduce the amount of space that a series of text or paragraphs takes up, and allows people to focus on one piece of content at a time, or skim through quickly and only open the panels that are relevant to them.

In Drupal, there are a variety of ways to go about building an accordion. You can use a content type, paragraph type, or even make a view mode that allows multiple types of content to utilize the accordion’s functionality. For this example, we’re going to use a paragraph type to make an FAQ accordion panel. We only need two fields, one, a plain text question field and a long formatted text field for the answer.

Once we have our paragraph type and fields created, with the labels hidden in our display, we create a twig template to format the content. It will look something like this:

{# These variables unique IDs and aria attributes utilizing paragraph ID instead of relying on JS to loop through and append unique numbers #}

{% set ariaId = 'faq-answer--' ~ paragraph.id() %}

{% set ariaTitle = 'faq-title--' ~ paragraph.id() %}

{# HTML structure for far widget #}
<div class=“paragraph paragraph--faq">
  <div class="card-inner">
    <h3 class="faq-header">
      <button class="faq-question" aria-controls="{{ ariaId }}" aria-expanded="false" id="{{ ariaTitle }}">{{ content.field_faq_title }}</button>
    </h3>
    <div role="region" class="faq-answer" id="{{ ariaId }}" aria-hidden="true" aria-labelledby="{{ ariaTitle }}">
      {{ content|without(‘field_faq_title’) }} 
    </div>
  </div>
</div>

Here are the essential parts for the accessibility of the accordion panel:

• heading element wrapped around a button
• button control attributes:
  • aria-controls: value is unique ID of the region of corresponding panel
  • id: unique ID for title, called in aria-labelledby attribute of corresponding panel
  • aria-expanded: value will toggle between false and true when panel is opened
  • class (optional): used to help responsively style button controls
• panel attributes:
  • role=“region”
  • id: unique ID of panel, called in corresponding button’s aria-controls attribute
  • aria-labelledby: same as corresponding button’s unique ID
  • aria-hidden: false toggles between true and false when panel is opened
  • class (optional): to style the accordion panels

These attributes all work together to allow users to be able to tab through the accordion buttons list, open and close each one, and know which button corresponds with which panel.

Now that we have the necessary HTML structure and attributes in place, it's time to make our accordion functional with some jQuery:

(function ($, Drupal) {
  'use strict';

  Drupal.behaviors.faqAccordion = {
    attach: function (context, settings) {
      $(context).find(‘.paragraph--faq').once('faqAccordion').each(function () {
        var $faq = $(this);
        var $question = $faq.find('.faq-question');
        var $answer = $faq.find('.faq-answer');
        $question.click(function () {
          if ($faq.hasClass('expanded')) {
            $faq.removeClass('expanded');
            $question.attr('aria-expanded', 'false');
            $answer.attr('aria-hidden', 'true');
          }
          else {
            $faq.addClass('expanded');
            $question.attr('aria-expanded', 'true');
            $answer.attr('aria-hidden', 'false');
          }
        });
      });
    }
  };
}(jQuery, Drupal));

This changes the necessary attributes to support the toggle function, and adds an additional class to the FAQ wrapper to allow for additional styling if desired.

If you are following these instructions, you may notice that the accordion does not in fact appear functional yet, but if you inspect the accordion you should see the attributes changing according to the jQuery function. This is because in this particular case we use CSS to finish out the functionality, relying on the aria-expanded and aria-hidden attributes for styling. Basing appearance of content on these attributes can be good practice for learning to build and style with accessibility in mind, since it is a reminder that if you cannot access the content, neither can someone using a screen reader or other assistive technology.

With this simple CSS snippet, we should now have a functional accordion:

.paragraph--faq .faq-answer[aria-hidden="true"] {
  display: none;
}

Additional styles can be added based on the aria-hidden attribute for the accordion panel and the aria-expanded attribute for the button. Just remember to keep accessible styles and best practices in mind as you do so.

Here are some examples of accordions we've built in Drupal:

• TWO MEN AND A TRUCK®
• Special Olympics Michigan
• Viking Digital Solutions

There you have it! You're now well on your way to optimizing your site for accessibility.