<main>
<h1>Disclosure Widgets</h1>
<p>
A disclosure widget is a simple show/hide control.
</p>
<p>
In HTML, this is represented with <a href="https://www.w3.org/TR/html51/interactive-elements.html#the-details-element"><code><details></code></a> and <a href="https://www.w3.org/TR/html51/interactive-elements.html#elementdef-summary"><code><summary></code></a> elements. In that construct, <code><summary></code> represents a summary or legend or caption for content that is contained within the <code><details></code> element. The <code><summary></code> also acts as the control that toggles display of the content within its associated <code><details></code>.
</p>
<details>
<summary>A native HTML disclosure.</summary>
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.
</details>
<p>
While modern browsers now support <code><details></code> / <code><summary></code>, the need for backward compatibility, consistent exposure in Assistive Technology (AT), and more discrete styling control sometimes warrants the use of an <a href="https://www.w3.org/TR/wai-aria-practices-1.1/#disclosure">ARIA disclosure widget</a>.
</p>
<h2>ARIA disclosure widget construct</h2>
<p>
The structure is straightforward. A <code><button></code> (or a control with <code>role="button"</code>) acts as the control that toggles display.
</p>
<p>
Add <code>aria-expanded</code> with either <code>true</code> or <code>false</code> to convey to AT whether the widget is expanded or not.
</p>
<p>
Add <code>aria-controls</code> with with the value of the <code>id</code> 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.
</p>
<h3>Keyboard Interaction</h3>
<p>
When the disclosure control has focus:
</p>
<ul>
<li><kbd>Enter</kbd>: activates the disclosure control and toggles the visibility of the disclosure content.</li>
<li><kbd>Space</kbd>: activates the disclosure control and toggles the visibility of the disclosure content.</li>
</ul>
<h3>WAI-ARIA Roles, States, and Properties</h3>
<ul>
<li>The element that shows and hides the content has <a href="https://www.w3.org/TR/wai-aria-1.1/#button">role <code>button</code></a>.</li>
<li>When the content is visible, the element with role <code>button</code> has <a href="https://www.w3.org/TR/wai-aria-1.1/#aria-expanded"><code>aria-expanded</code></a> set to <code>true</code>. When the content area is hidden, it is set to <code>false</code>.</li>
<li>Optionally, the element with role <code>button</code has a value specified for <a href="https://www.w3.org/TR/wai-aria-1.1/#aria-controls"><code>aria-controls</code></a> that refers to the element that contains all the content that is shown or hidden.</li>
</ul>
<h2 id="Style1">Disclosure Style 1</h2>
<p>
This uses a native HTML <code><button></code> as the control, enhanced with <code>aria-expanded</code> to expose the state to screen reader users and the CSS. Attribute selectors (<code>[aria-expanded]</code>, <code>[aria-expanded="true"]</code>, and <code>[aria-expanded="false"]</code>) along with the general sibling combinator (<code>~</code>) 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.
</p>
<p>
In this example only the arrow circle is the control. This is a departure from how a standard <code><details></code> / <code><summary></code> works, where the full text would be the control.
</p>
<div>
<button type="button" id="btnDisc01" aria-expanded="false" onclick="toggleDisclosure(this.id);" aria-labelledby="Disclosure01" aria-controls="Disclosed01">
<svg xmlns="\http://www.w3.org/2000/svg"" viewBox="0 0 80 80" focusable="false">
<path d="M70.3 13.8L40 66.3 9.7 13.8z"></path>
</svg>
</button>
<span id="Disclosure01">ARIA Disclosure Widget</span>
<div id="Disclosed01" class="disclosee">
<p>
The CSS needed to make this work:
</p>
<pre>button[aria-expanded="true"] ~ .disclosee {
display: block;
}
button[aria-expanded="false"] ~ .disclosee {
display: none;
}</pre>
</div>
</div>
<h2 id="Style2">Disclosure Style 2</h2>
<p>
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.
</p>
<div>
<span id="Disclosure02">Disclosure Style 2</span>
<button type="button" id="btnDisc02" aria-expanded="false" onclick="toggleDisclosure(this.id);" aria-labelledby="Disclosure02" aria-controls="Disclosed02">
<svg xmlns="\http://www.w3.org/2000/svg"" viewBox="0 0 80 80" focusable="false">
<path d="M70.3 13.8L40 66.3 9.7 13.8z"></path>
</svg>
</button>
<div id="Disclosed02" class="disclosee" role="group" aria-labelledby="Disclosure02">
<div>
<input type="checkbox" name="D02" id="D02-01">
<label for="D02-01">Example Item</label>
</div>
<div>
<input type="checkbox" name="D02" id="D02-02">
<label for="D02-02">Another Example</label>
</div>
<div>
<input type="checkbox" name="D02" id="D02-03">
<label for="D02-03">Third Item</label>
</div>
</div>
</div>
<h2 id="Style3">Disclosure Style 3</h2>
<p>
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 <code><button></code>s that also is exposed to screen readers, there is a distinct form, and there is a link.
</p>
<div>
<button type="button" id="btnDisc03" aria-expanded="false" onclick="toggleDisclosure(this.id);" aria-controls="Disclosed03">
<div>
<div>
Disclosure Style 3
</div>
<span>
<svg xmlns="\http://www.w3.org/2000/svg"" viewBox="0 0 80 80" focusable="false">
<path d="M70.3 13.8L40 66.3 9.7 13.8z"></path>
</svg>
</span>
</div>
</button>
<div id="Disclosed03" class="disclosee">
<p id="Disclosed03_Group01">
This may be a grouping
</p>
<ul>
<li><button type="button" aria-describedby="Disclosed03_Group01">Fake option number one</button></li>
<li><button type="button" aria-describedby="Disclosed03_Group01">Second thing you can do</button></li>
</ul>
<p id="Disclosed03_Group02">
Also a group
</p>
<ul>
<li><button type="button" aria-describedby="Disclosed03_Group02">This one is not different</button></li>
<li><button type="button" aria-describedby="Disclosed03_Group02">Neither is this one</button></li>
<li><button type="button" aria-describedby="Disclosed03_Group02">I have no idea why this is here</button></li>
</ul>
<p id="Disclosed03_Group03">
Dates for some reason
</p>
<form>
<div>
<label for="DateStart">Start <small>(MM/DD/YYYY)</small></label>
<input type="text" id="DateStart" size="8" aria-describedby="Disclosed03_Group03">
</div>
<div>
<label for="DateEnd">End <small>(MM/DD/YYYY)</small></label>
<input type="text" id="DateEnd" size="8" aria-describedby="Disclosed03_Group03">
</div>
<div>
<input type="submit" value="Submit">
</div>
</form>
<a href="">A link to maybe a help file?</a>
</div>
</div>
<h2 id="Style4">Disclosure Style 4</h2>
<p>
Disclosures can act as a form of tool-tip, making content available to screen readers before activation, such as via <code>aria-describedby</code> 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.
</p>
<div>
<button type="button" id="btnDisc04" aria-expanded="false" onclick="toggleDisclosure(this.id);" aria-labelledby="btnDisc04_info Disclosure04" aria-describedby="Disclosure04" aria-controls="Disclosed04">
?
<span id="btnDisc04_info" class="visually-hidden">More info about</span>
</button>
<span id="Disclosure04">The Battle of Hastings</span>
<div id="Disclosed04" class="disclosee" role="region" aria-describedby="Disclosure04" tabindex="0">
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</div>
</div>
<h2 id="Style5">Disclosure Style 5</h2>
<p>
Disclosure widgets can take the place of a multi-select control (<code><button></code>) 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 <code><label></code> pointing at the <code><button></code>. Be warned that the label text will override the text node within the <code><button></code>. In this case we use the <code><button></code> text to provide a visible count of checked items with <code><output></code> making it available to screen readers.
</p>
<p>
This supports arrow key navigation, though you have to <kbd>Tab</kbd> into the expanded content first (this is intentional). It also supports <kbd>Home</kbd> and <kbd>End</kbd>. I am not using script to trap any key presses to stop the page from also jumping, I am using CSS <a href="https://drafts.csswg.org/css-overscroll-1/#overscroll-behavior-properties"><code>overscroll-behavior</code></a>, which is not well supported but for which this page acts as a test. You will need to add your own script.
</p>
<label for="btnDisc05" id="lblDisc05">Disclosure Style 5 Label</label>
<div>
<button type="button" id="btnDisc05" aria-expanded="false" onclick="toggleDisclosure(this.id);" aria-controls="Disclosed05">
<span>
<output>
<span id="Disc05Count">0</span> Items Selected
</output>
<span>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80" focusable="false">
<path d="M70.3 13.8L40 66.3 9.7 13.8z"></path>
</svg>
</span>
</span>
</button>
<div id="Disclosed05" class="disclosee" role="group" aria-labelledby="lblDisc05">
<label for="D05-01">
<input type="checkbox" name="D05" id="D05-01" onclick="countChecked('D05','Disc05Count');">
Example Item
</label>
<label for="D05-02">
<input type="checkbox" name="D05" id="D05-02" onclick="countChecked('D05','Disc05Count');">
Another Example
</label>
<label for="D05-03">
<input type="checkbox" name="D05" id="D05-03" onclick="countChecked('D05','Disc05Count');">
Third Item
</label>
<label for="D05-04">
<input type="checkbox" name="D05" id="D05-04" onclick="countChecked('D05','Disc05Count');">
Fake Item
</label>
<label for="D05-05">
<input type="checkbox" name="D05" id="D05-05" onclick="countChecked('D05','Disc05Count');">
For Testing Only
</label>
<label for="D05-06">
<input type="checkbox" name="D05" id="D05-06" onclick="countChecked('D05','Disc05Count');">
Sixth Example
</label>
<label for="D05-07">
<input type="checkbox" name="D05" id="D05-07" onclick="countChecked('D05','Disc05Count');">
Item Number Seven is Lengthy
</label>
<label for="D05-08">
<input type="checkbox" name="D05" id="D05-08" onclick="countChecked('D05','Disc05Count');">
This Is Also Fake
</label>
<label for="D05-09">
<input type="checkbox" name="D05" id="D05-09" onclick="countChecked('D05','Disc05Count');">
Ninth Item
</label>
</div>
<h2>Variations</h2>
<p>
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.
</p>
<h3>Closing the Widget</h3>
<p>
Each of these examples closes when the user presses <kbd>Esc</kbd>. This does not always make sense (as in the first example) and does not correspond to the native <code><details></code> / <code><summary></code> experience. However, there are many cases where closing (hiding) on <kbd>Esc</kbd> make sense, particularly where your control can obscure other content.
</p>
<p>
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.
</p>
<h3>Managing Focus</h3>
<p>
Disclosure widgets do not move focus to the content area that is displayed. For your users, there may be cases where that makes sense.
</p>
<p>
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 (<code>tabindex</code> attribute) and have an accessible name and appropriate group role. See <em>Disclosure Style 4</em> as an example, though it does automatically not move focus.
</p>
<h3>Arrow Key Navigation</h3>
<p>
If you are using a visual style that looks like a <code><select></code>, 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 <kbd>Home</kbd>, <kbd>End</kbd>, <kbd>Page Up</kbd>, <kbd>Page Down</kbd> and potentially <kbd>Shift</kbd> + <kbd>F10</kbd>.
</p>
<p>
Remember that screen readers intercept these keys, so do not build your control to rely on these keys being pressed.
</p>
<h3>Displaying on Hover or Focus</h3>
<p>
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.
</p>
<p>
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 <kbd>Esc</kbd> support above). See <a href="https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html">Success Criterion 1.4.13: Content on Hover or Focus (AA, WCAG 2.1)</a> for more detail.
</p>
<h2>External Resources and Examples</h2>
<ul>
<li><a href="https://www.w3.org/TR/wai-aria-practices-1.1/#disclosure">ARIA disclosure widget</a> from WAI-ARIA Authoring Practices 1.1
<ul>
<li><a href="https://www.w3.org/TR/wai-aria-practices-1.1/examples/disclosure/disclosure-img-long-description.html">Disclosure (Show/Hide) of Image Description</a></li>
<li><a href="https://www.w3.org/TR/wai-aria-practices-1.1examples/disclosure/disclosure-faq.html">Disclosure (Show/Hide) of Answers to Frequently Asked Questions</a></li>
<li><a href="https://www.w3.org/TR/wai-aria-practices-1.1examples/disclosure/disclosure-navigation.html">Disclosure (Show/Hide) for Navigation Menus</a></li>
</ul>
</li>
<li><a href="https://adrianroselli.com/2019/06/link-disclosure-widget-navigation.html">Link + Disclosure Widget Navigation</a></li>
</ul>
<!--
<p>
Arrow key navigation example: <a href="https://codepen.io/aardrian/pen/pxejNz">https://codepen.io/aardrian/pen/pxejNz</a>
</p>
-->
</main>
!
