Details / Summary Are Not [insert control here]

Once major browsers started supporting <details> & <summary> developers immediately started to play with them to see what sorts of patterns they could enhance or replace. This is a good thing. Experimentation pushes boundaries, improves understanding.

However, we need to be careful of christening this new-to-us interaction as the solution to all our coding struggles. After all, a responsible developer would not tear out the guts of one control and replace them with another without first confirming they are accessible, robust, consistent across browsers, and many other things that could otherwise harm users.

A responsible developer would test it first. Before declaring it as an alternative to any other tested solution, a responsible developer would ensure these tests produced results that were at least as good as, or better than, existing solutions.

JavaScript Required

Whether or not you like it, Internet Explorer and Edge are still browsers that exist, and will likely exist for some time to come. Locked-down corporate environments will not magically move to Chromium Edge overnight (or over-year). They do not natively support <details> & <summary>.

Any claims that <details> & <summary> are a script-free solution or are a way to make more complex widgets in a progressively enhanced way are false. You will need a polyfill to support these browsers already.

I provide a link to that polyfill and a working example in a Codepen I made for another post.

Update: 16 June 2021: Chromium Edge supported <details> & <summary> at the official launch, January 2020, which came about 8 months after this post was written. With Legacy Edge effectively gone in the wild, you can not worry about it. Internet Explorer still has another year of partial support (as of this writing) and so may exist among your audience. Further, JavaScript will still be required for any interactions or uses beyond hiding or showing content regardless of the browser support for <details> & <summary>.

They Are Not…

I am going to point out what this element pair cannot do in its native form. While <details> & <summary> can be enhanced with script and ARIA to do these tasks, in each case there are already existing solutions that are tested and which are consistent across platforms.

I give the ARIA Authoring Practices some flak for applying overly-complex patterns in unnecessary ways (navigation, for example), but it at least provides a baseline to target for some patterns before testing with users.

…An Accordion

The accordion pattern points out that you would need to use heading, button, and region roles, identifies that the arrow keys (among others) do some work, and only one panel should be visible at a time.

At the very least you will need script to manage states with aria-controls and aria-expanded as well as the additional keyboard interaction.

Added 9 August 2023: Now that support is extant in evergreen browsers, I have identified how to make a group of <details> & <summary> into an accordion. It still requires ARIA and JavaScript, however. Read Progressively Enhanced HTML Accordion.

…A Tab Set

The tabs pattern similarly notes all the custom keyboard interactions needed, the same prohibition on showing multiple tab panels, but also has its own ARIA roles of tab, tablist, and tabpanel, which need to be wired up with script and other ARIA properties.

The script wiring manages state by manipulating aria-controls and aria-haspopup. All of these make sense via aria-labelledby and aria-haspopup.

2 October 2024: With the standardization of exclusive accordions causing folks to revisit this, on Mastodon I outline differences in the allowed content models and actual support and Curtis Wilcox points out the difference in DOM structure (which impacts reading and focus order).

…Menu Navigation

Definitely ignore the ARIA Authoring Practices here. Fly-out navigation (navigation with hidden options under primary options) has existed for years. There are plenty of cases of accessible navigation, even with new WCAG 2.1 SCs necessitating the ability to close them on Esc.

The simplest approach to navigation is not to need sub-menus. If you do, however, a simple nested list of links enhanced with JavaScript is still your best bet, as I demonstrate in Link + Disclosure Widget Navigation.

Update: 2 March 2022

Chrome will now expand a <details> if an in-page search finds hits within it. So either let it happen or script it away. As this example shows, you can get some unfortunate flicker (it happened on every key press, but the video only captures some of them).

…A Custom Menu

This begs the question of what it is you really want. Do you want to replace the native <select>? Look at the listbox pattern. Or are you thinking more native, and want to replace the kind of menu you see in Windows, macOs, or elsewhere? Look at the menubutton pattern.

By now you can probably guess that each has its own keyboard interactions, ARIA roles, states, and properties that must be managed when rendered and while used.

…A Modal Dialog

The dialog pattern does not sound complex, at least no more complex than the previous controls, but it has its own challenges. First make sure you get that dialog role in there. And make sure it can be dismissed with an Esc press.

But also know that you have to do things like restrict focus in the dialog and render the underlying page inert, unable to get focus. This is hard to do when your fake-dialog lives within the page content, instead of as a sibling to it.

If you can sort that out, you now have the climb the mountain of some of the gotchas just to get to parity with existing options, but then you are on the hook for even more quirks.

Wrap-up

By all means, experiment. This is how you and the industry learns. This is how we come up with new patterns, some of which are great (CSS grid), some of which are crap (🍔).

But please take some time to test with various browsers, versions, platforms, devices, assistive technology, connection speeds, and most importantly, users.

Just because you see a pattern on your favorite site does not in itself signal that it is a good pattern. It may actually signal that your favorite site did not test these things.

Also, a shout-out to Scott O’Hara, who not only helped with a quick review of this post but as I noted earlier is out there every day trying to prevent devs from foot-gunning themselves.

Update: December 6, 2019

During a Twitter convo tonight Scott reminded that the <summary> can neuter semantics of nested elements:

re: the HTML specification "yes" you could do that.

but, summary is typically mapped to buttons

buttons treat elements within them as having no (presentational) semantics

so
summary > h#
may well be the same as
summary > span.lol-whatever

😬

Michael Fairchild reminded that current implementation is inconsistent. When he posted this, I was confirming that Firefox with NVDA recognized an <h#> inside a <summary>.

FWIW, Some further context and tests that I did a while back re headings in summary elements. Support is mixed (as was already suggested). a11ysupport.io/tests/tech__html__details-summary

If you are already familiar with how role="tab" kills the semantics of nested elements, then move <summary> into that part of your brain — until support exists across all screen reader and browser pairings.

Update: September 13, 2022

Scott O’Hara discusses The details and summary elements, again, wading deeply into features, accessibility bits, and support. He also compares and contrasts with an ARIA disclosure widget. I recommend you read it if you plan to use these elements as any of the types of interface widgets listed in this post.

Update: November 7, 2022

Over at the Cloud Four blog, Gerardo Rodriguez makes the case that A details element as a burger menu is not accessible. While the evidence includes links to some older tests at a11ysupport.io, the concerns are still valid and the support may still be as squishy.

I have also been asked about using <details> & <summary> for my Link + Disclosure Widget Navigation. I have argued against it before, if for no other reason than the expand-on-search feature in Chrome.

Update: August 9, 2023

Now that support is extant in evergreen browsers, I have identified how to make a group of <details> & <summary> into an accordion. It still requires ARIA and JavaScript, however. Read Progressively Enhanced HTML Accordion.