Disclosure Widgets
A disclosure widget is a simple show/hide control.
In HTML, this is represented with <details> and <summary> elements. In that construct, <summary> represents a summary or legend or caption for content that is contained within the <details> element. The <summary> also acts as the control that toggles display of the content within its associated <details>.
A native HTML disclosure.
This content is hidden in supporting browsers until a user activates it. For non-supporting browsers (IE11 without a polyfill) then this content will always be displayed.
While modern browsers now support <details> / <summary>, the need for backward compatibility, consistent exposure in Assistive Technology (AT), and more discrete styling control sometimes warrants the use of an ARIA disclosure widget.
ARIA disclosure widget construct
The structure is straightforward. A <button> (or a control with role="button") acts as the control that toggles display.
Add aria-expanded with either true or false to convey to AT whether the widget is expanded or not.
Add aria-controls with with the value of the id from the element whose visibility is being toggled. This is optional, and support in AT is sparse, but this programmatic association allows for easier reference via CSS or script.
Keyboard Interaction
When the disclosure control has focus:
- Enter: activates the disclosure control and toggles the visibility of the disclosure content.
- Space: activates the disclosure control and toggles the visibility of the disclosure content.
WAI-ARIA Roles, States, and Properties
- The element that shows and hides the content has role
button. - When the content is visible, the element with role
buttonhasaria-expandedset totrue. When the content area is hidden, it is set tofalse. - Optionally, the element with role
buttonaria-controlsthat refers to the element that contains all the content that is shown or hidden.
Disclosure Style 1
This uses a native HTML <button> as the control, enhanced with aria-expanded to expose the state to screen reader users and the CSS. Attribute selectors ([aria-expanded], [aria-expanded="true"], and [aria-expanded="false"]) along with the general sibling combinator (~) ensure the programmatic state drives the visual display. This means you should not have to manage CSS either inline, via classes, or otherwise. It also makes it harder for the visual display to fall out of sync with the programmatic state.
In this example only the arrow circle is the control. This is a departure from how a standard <details> / <summary> works, where the full text would be the control.
The CSS needed to make this work:
button[aria-expanded="true"] ~ .disclosee {
display: block;
}
button[aria-expanded="false"] ~ .disclosee {
display: none;
}
Disclosure Style 2
This represents another way to style a disclosure, common for menu-like controls that you want to display from toolbars, within table cells, and so on.
Disclosure Style 3
Disclosure widgets can contain richer content than just options in a list. while you do not want to overload them, it is possible to mix controls. In the following example there is visible grouping for a set of <button>s that also is exposed to screen readers, there is a distinct form, and there is a link.
Disclosure Style 4
Disclosures can act as a form of tool-tip, making content available to screen readers before activation, such as via aria-describedby or by activating the control. You want to pay attention to window size and content length while also not clipping content. If there is no interactive content, then the entire container must be able to accept focus so a keyboard-only user can scroll to see it all.
Fought on 14 October 1066 between the Norman-French army of William, the Duke of Normandy, and an English army under the Anglo-Saxon King Harold Godwinson, beginning the Norman conquest of England. It took place approximately 7 miles (11 kilometres) northwest of Hastings, close to the present-day town of Battle, East Sussex, and was a decisive Norman victory.
The background to the battle was the death of the childless King Edward the Confessor in January 1066, which set up a succession struggle between several claimants to his throne. Harold was crowned king shortly after Edward's death, but faced invasions by William, his own brother Tostig, and the Norwegian King Harald Hardrada (Harold III of Norway). Hardrada and Tostig defeated a hastily gathered army of Englishmen at the Battle of Fulford on 20 September 1066, and were in turn defeated by Harold at the Battle of Stamford Bridge five days later. The deaths of Tostig and Hardrada at Stamford Bridge left William as Harold's only serious opponent. While Harold and his forces were recovering, William landed his invasion forces in the south of England at Pevensey on 28 September 1066 and established a beachhead for his conquest of the kingdom. Harold was forced to march south swiftly, gathering forces as he went.
The exact numbers present at the battle are unknown; modern estimates are around 10,000 for William and about 7,000 for Harold. The composition of the forces is clearer; the English army was composed almost entirely of infantry and had few archers, whereas only about half of the invading force was infantry, the rest split equally between cavalry and archers. Harold appears to have tried to surprise William, but scouts found his army and reported its arrival to William, who marched from Hastings to the battlefield to confront Harold. The battle lasted from about 9 am to dusk. Early efforts of the invaders to break the English battle lines had little effect; therefore, the Normans adopted the tactic of pretending to flee in panic and then turning on their pursuers. Harold's death, probably near the end of the battle, led to the retreat and defeat of most of his army. After further marching and some skirmishes, William was crowned as king on Christmas Day 1066.
There continued to be rebellions and resistance to William's rule, but Hastings effectively marked the culmination of William's conquest of England. Casualty figures are hard to come by, but some historians estimate that 2,000 invaders died along with about twice that number of Englishmen. William founded a monastery at the site of the battle, the high altar of the abbey church supposedly placed at the spot where Harold died.
Disclosure Style 5
Disclosure widgets can take the place of a multi-select control (<button>) without taking up the space or leaning on the confusing interface. Checkboxes will be obvious and get their necessary group label from the container. To look more like a traditional control, use <label> pointing at the <button>. Be warned that the label text will override the text node within the <button>. In this case we use the <button> text to provide a visible count of checked items with <output> making it available to screen readers.
This supports arrow key navigation, though you have to Tab into the expanded content first (this is intentional). It also supports Home and End. I am not using script to trap any key presses to stop the page from also jumping, I am using CSS overscroll-behavior, which is not well supported but for which this page acts as a test. You will need to add your own script.
Variations
Each of the examples above warrants testing with real users — specifically the users of your product / service / screens. That testing should include people with disabilities, ideally whose skill levels correspond to your audience.
Closing the Widget
Each of these examples closes when the user presses Esc. This does not always make sense (as in the first example) and does not correspond to the native <details> / <summary> experience. However, there are many cases where closing (hiding) on Esc make sense, particularly where your control can obscure other content.
Some design implementations may warrant closing (hiding) the additional when a user clicks or taps outside the content area, particularly when used as navigation or controls that resemble native form elements. These examples do not implement that behavior.
Managing Focus
Disclosure widgets do not move focus to the content area that is displayed. For your users, there may be cases where that makes sense.
In those scenarios determine if moving focus to the first interactive item is the best fit, or to the container instead. If you move focus to the container, note that the container must be able to accept focus (tabindex attribute) and have an accessible name and appropriate group role. See Disclosure Style 4 as an example, though it does automatically not move focus.
Arrow Key Navigation
If you are using a visual style that looks like a <select>, then you may want to add support for arrow keys. Bear in mind, if you do that you will also want to add support for Home, End, Page Up, Page Down and potentially Shift + F10.
Remember that screen readers intercept these keys, so do not build your control to rely on these keys being pressed.
Displaying on Hover or Focus
Generally you want to avoid revealing the hidden content when a control receives focus or is hovered. Tool-tips are a valid exception, but in most other cases this will produce usability challenges.
If you pursue it, ensure that there is no nested interactive content, as a user may be unable to access it when only hovering. Unless the revealed content persists. Which means it will also need to be dismissable (see Esc support above). See Success Criterion 1.4.13: Content on Hover or Focus (AA, WCAG 2.1) for more detail.