Chapter Eight. Collapsible Content

With the ever-growing complexity of websites and web applications, designers often choose to selectively hide and show content on the screen, either by progressively revealing content based on user actions, or by providing content in collapsible blocks that users can selectively toggle on and off.

Content blocks that let users selectively toggle their display have a myriad of common design forms and even more names—collapsibles, spin-downs, toggle panels, twisties, and content disclosures, to name just a few. There’s a wide range of scenarios where collapsible content is useful:

• For detailed information that isn’t essential to see at all times or for all users, but may be helpful in select cases, such as documentation describing a technical issue

• For optional fields in a form, like user preference settings for a registration form, or the gift-wrap options in an ecommerce checkout workflow

• For tool panes or grouped palette panels in desktop-style web applications, where the user can choose which elements should be collapsed or expanded to optimize screen real estate

When content is presented inside a collapsible widget, it’s a common best practice to display a visual indicator such as an arrow or plus/minus icon along with a clickable label or other element to let users know there’s additional content available.

It’s also important to ensure that selectively hidden content remains accessible to screen readers by adding appropriate ARIA attributes, supporting keyboard access, and using the optimal CSS properties to properly manage visibility. In this chapter, we’ll discuss how to build collapsible content in an accessible way.

X-ray perspective

Let’s consider a common case where collapsible content is used: a feedback message for a technical error. In our photo manager site, when a user has completed uploading a batch of photos, a feedback panel may appear to summarize the total number of issues, and provide details about specific upload issues, and in a simple and compact format:

Figure 8-1 Target design with details panel collapsed

For users interested in knowing which photos have issues and what specific problem occurred, we’ll provide a Details heading that, when clicked, will expand a panel to show the full list of photo issues. To indicate that the Details heading will reveal more content, a small arrow is placed to the left; when the panel expands, the arrow orientation points downward.

Figure 8-2 Target design with details panel expanded

Looking at the collapsible details panel with our x-ray perspective, we note that the detail content provided in the panel may be necessary to help the user in the basic experience understand what to do next. For that reason, we need to ensure that it is included in its entirety in the foundation markup. In the enhanced experience, we’ll use JavaScript and CSS to hide the contents by default, and add the arrow icons and click behavior to expand or collapse the content when users click on the Details heading.

There’s one crucial point to consider for the foundation markup: the Details heading acts as a title for the collapsible component, so it should be marked up as a heading element (h2) to take advantage of the semantics that headings afford.

Beyond that, the content that sits within the collapsible pane can be formatted with any semantic HTML. In this case, each line contains only two items of data—the filename (we’ll use a background image for the icon) and the issue description—and the formatting is quite simple, so we can use an unordered list to keep the markup very lightweight. By wrapping the issue description in an emphasis tag (em), we can use CSS to float it right to look like our design. (If our details data included any additional data fields, or would benefit from explanatory headers, we would most likely mark it up as a table.)

Figure 8-3 The basic experience displays all collapsible content so it’s accessible.

A couple of important accessibility features must be factored into the enhanced markup and script to ensure that it follows best practice norms for screen-reader users.

People using screen readers will expect that expanded content will be read, and collapsed content to be skipped, when the page is read aloud. To prevent collapsed content from being read, we hide it using display: none in the enhanced CSS, and mark it with aria-hidden="true" in the DOM.

Hiding the collapsed content this way is fine, as long as screen-reader users are informed that it’s there, and are provided with a way to access it. The enhancement script will make the few necessary markup modifications to the Details heading:

• The heading needs a cue to let users know it contains more content. To provide clear instructions, the script will insert a span before the heading’s text, detect the current state of the collapsible pane, and append the text “Show” when content is collapsed or “Hide” when it’s expanded (note the trailing space in the text, which makes sure the screen reader pauses before reading the heading text). The screen reader will read the more descriptive “Show Details” or “Hide Details” to explain what will happen when the user clicks. These span elements will be accessibly hidden off-screen so they’re not visible on the page.

• The heading must be able to receive keyboard focus. The script will wrap an anchor element (a) around the text inside the heading tag, which makes it navigable when the user presses the Tab key.

Now that we have a good sense of how the basic and enhanced experiences will be created, we can move on to writing the foundation markup and styles.

Creating accessible collapsible content

It’s a fairly simple process to create collapsible content widgets that are fully accessible in both the basic experience and with screen readers in the enhanced experience.

In the following code walkthrough, we’ll focus specifically on the clickable heading and the collapsible portion of our target design:

Figure 8-4 The collapsible portion of the target design

Foundation markup and style

The foundation markup for the collapsible panel is simply a heading followed by an unordered list. Within each list item, the issue description is wrapped in an emphasis tag to differentiate it from the filename:

For the basic style sheet, we’ll set the font on the body tag, and style each em element to display: block to make the issue description sit on a new line:

body { font-family: "Segoe UI", Arial, sans-serif; }
ul li em { display: block; }

In the basic experience, all content is visible at all times, with no collapsible behavior. With the safe styles applied, it’s easy to read and is organized into a clear visual hierarchy:

Figure 8-5 Basic experience with safe styles applied

Enhanced markup and style

To style the expanded and collapsed states in the enhanced experience, we’ll need to identify the classes that the script will apply to the markup to add style and enable showing and hiding behavior.

The Details heading is assigned a class of collapsible-heading, and the content ul is assigned a class of collapsible-content. These classes will be used to define the appearance of the expanded state—orienting the heading’s arrow icon to point down, and making the details content visible on the screen:

When a user clicks the heading to hide detail content, the script adds a class of collapsible-heading-collapsed to the heading that swaps the arrow icon to point to the right, and adds a class of collapsible-content-collapsed to the list to hide it both onscreen and from most screen readers. The script will also update the aria-hidden attribute to match:

As we discussed in the x-ray section, the heading needs additional markup to make it accessible with keyboard navigation and provide contextual instruction for screen readers.

First, a link with a class of collapsible-heading-toggle is wrapped around the heading text so it’s accessible to keyboard users. Adding an ARIA role of button identifies the element’s function in browsers that are aware of the newer, ARIA markup:

The script will also inject a span before the text, with the class of collapsible-heading-status, which we will use to provide instructions for screen readers. The script will include logic to deliver the proper span text depending on the collapsible panel’s state.

When the content is expanded and the link has focus, the screen reader will read the link text as “Hide Details”:

When collapsed, the link will be read as “Show Details”:

With the markup and class names established, we can write enhanced style rules against it that will apply the necessary styles for the widget.

First, we’ll set a global font size in the enhanced style sheet that will simplify how we set font sizes for elements within our widget. We’ll assign a font-size property to the body element that “resets” the standard browser default size.

We prefer to use the relative em unit to set font sizes so that users can more easily adjust text size to their liking with browser preferences and key commands. The base font size for most browsers is 16 pixels; by setting the body font size to 62.5% of 16 pixels, we effectively “reset” a single em unit (1em) to 10 pixels:

body { font-size: 62.5% }

With the base font size set as a percentage, em designations will translate to simple multiples—1.5 em equals 15px, 2.2 em is 22px, and so on—which greatly reduces our need to calculate each element’s text size, and preserves scalability for users who change their default size or use keyboard commands like Ctrl-plus or Ctrl-minus to resize on the fly.

Next, we’ll write style rules for the classes, without specifically referencing the elements to which they are applied. This generic approach allows our collapsible behavior to work properly on different combinations of HTML elements, such as an h3 followed by a p.

The collapsible-heading needs 15 pixels of left padding to make space for the arrow background image:

The arrow background image is a sprite containing both the expanded (down-facing) and collapsed (right-facing) states. When the collapsed class is present, the background position shifts to display the right-facing arrow:

.collapsible-heading-collapsed {
   background-position: 0 -84px;
}

We want our header to match our target design, which means we don’t want the h2 to inherit the toggle link’s default underline, so we’ll remove it:

.collapsible-heading-toggle {
   text-decoration: none;
}

(This is optional; if you do want the header of a collapsible container to retain the native underline to look like a link, simply skip this step.)

When the unordered list content has the collapsed state class, we set the display property to none to hide it both on the screen and for screen readers:

.collapsible-content-collapsed {
   display: none;
}

To keep the span before the heading (“Hide” or “Show”) in place to be read by screen readers but hidden on screen, we position it far off-screen:

Finally, we’ll apply formatting and style to the collapsible widget content to make it appear closer to our target design. This portion of the visual design is tied to specific elements (h2, ul), so we’ll specify them in our selectors:

We now have the foundation markup structure and styles for the fully accessible expanded and collapsed states of our widget.

Figure 8-6 Collapsed (top) and expanded (bottom) states of the widget

Collapsible enhancement script

The enhancement script will transform foundation markup into the enhanced widget by automating the addition of new markup and classes, and attaching the click behavior to the heading to toggle the state classes.

Generating the enhanced markup

First, we’ll create variable references to our heading and content elements so we can manipulate them with the script:

For the heading, we’ll attach the collapsible-heading class, add the status span with show/hide text, and wrap the link tag around the heading text:

The content list is assigned the collapsibleContent class:

collapsibleContent
   .addClass('collapsible-content'),

Applying behavior to the enhanced markup

Next, the script will assign events to the heading to expand and collapse the content. We’ll use custom events here, which will allow us to programmatically trigger expand and collapse behavior from a mouse click on the header.

First, we’ll create a custom collapse event that assigns the collapsed classes to the heading, changes the status text to say “Show”, and adds the collapsed class and aria-hidden attribute to the content:

We’ll also create a custom event to expand the content, which follows the same general procedure as the collapse in reverse—removing and toggling attributes and changing the text to reflect the expanded state:

Triggering the custom expand/collapse events

Now that we’ve created custom events, we just need to trigger them at the appropriate times. The enhancement script will trigger the collapse event immediately at page load, to automatically collapse the content by default:

collapsibleHeading.trigger('collapse'),

We’ll also write logic to trigger the appropriate event when the user clicks the heading (expand if the content is collapsed, collapse if the content is expanded). We can do this with a simple if/else statement. When the click occurs, we’ll check to see if the collapsed class is present on the heading, and then trigger the appropriate event. We’ll finish the click event by returning it false to make sure the native link behavior doesn’t follow through (if it did, a # character would be appended to the URL, and most browsers would scroll to the top of the page):

We now have a fully functioning collapsible content widget that is entirely accessible with the keyboard and for screen readers.

Using the collapsible script

The demo and downloadable code that accompanies this book (available at www.filamentgroup.com/dwpe) includes a script, jQuery.collapsible.js, that wraps all of the principles in this chapter in an easy, reusable function you can apply to any element on the page.

To use this script, download and reference the same files listed in the collapsible demo page. To make a heading on your page act as a collapsible widget, simply call the collapsible method on it by specifying the jQuery selector:

$('h2').collapsible();

In this example, the collapsible script will apply the collapsible behavior to every h2 on the page. There is no need to specify which content block the plugin should expand and collapse, because it assumes that the very next element—the one immediately following the markup on which you call the collapsible method (the unordered list, in our example)—is the content.

Applying this behavior to every h2 may be a little too broad for real-world applications, so you could use jQuery’s selectors to find collapsible elements within a tighter scope, perhaps with an ID or class attribute, or a descendent selector like the following (which would apply collapsible behavior to all h2 elements within a specific div):

$('#main h2').collapsible();

* * *

We frequently use the techniques described in this chapter to show and hide content—both visually and for screen readers—in many enhanced experiences; they let us responsively target content and functionality to the appropriate audience.

These basic ideas and principles—for classing, applying keyboard access, adding useful instructional language, and hiding and showing—can be applied to any content on the page. They can be used to build more complex components, or create forms that interactively hide and show form elements based on user selections in an accessible way.