Details / Summary Are Not [insert control here]
Once major browsers started supporting
<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.
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
Any claims that
<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.
They Are Not…
I am going to point out what this element pair cannot do in its native form. While
<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.
The accordion pattern points out that you would need to use
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-expanded as well as the additional keyboard interaction.
…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
tabpanel, which need to be wired up with script and other ARIA properties.
The script wiring manages state by manipulating
aria-haspopup. All of these make sense via
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.
…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.
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
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
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.
Do details/summary pass as disclosure widgets?
Mostly yes. For supporting browsers, they do the job.
If you are already using valid disclosure widgets as outlined in the ARIA Authoring Practices, as you linked, then I would recommend not changing them to
Partly because of browser incompatibility, partly because of inconsistent support, and partly because the user experience for at least screen readers will change when you swap.
Of course details and summary are not accordions – and I’m grateful for this.
I have no idea. why someone invented them in the first place. Accordeons suck! It should be up to the user to decide, how much text he or she wants to reveal. Accordeons usually are part of pages with a lot of text. If I visit a page with a lot of text, first thing I do, I open all hidden “things”. hit cmd+f and search for the terms I’m interested in. I have no idea. And of course I’m not patient enough to read all texts instead. So I frequently leave pages with accordions.
details and summary are the things authors should use instead of accordeons!
For better or worse, clients frequently request accordions for things like FAQs, etc. The chief benefits are to save space and facilitate quick visual scanning of the headings list. But there’s a cost: you lose search-ability of the content and you can annoy users. If you’re going to implement an accordion, you should probably include Open All and Close All buttons to make things easier for the user. The problem with
detailswidgets is the inconsistency in how different browsers and screen readers implement the
summaryelement and support headings as children of
summary. The HTML specs don’t help much, because while the implicit role of
summarycan also contain headings. But the semantics of those headings have to be respected, and buttons don’t do this. It’s like a Catch-22. If this gets solved, I’d dump accordions in favor of details in a second.
[…] clients frequently request accordions for things like FAQs, etc. The chief benefits are to save space and facilitate quick visual scanning of the headings list.
Clients often conflate a requirement with a technical implementation. Historically I have had good luck making a normal page with headings, and putting a list of links at the top — each link replicating the text of the heading and linking to it.
Then users get the ability to quickly scan plus the added benefit of being able to save and share the link to the specific piece of content.
For clients who also think that saving space is important, I remind them that on the web, scrollbars and full-bleed colors are free.
To your broader point, I agree the default implementation of
<summary>is lacking. The accordion pattern also should not extend outside the viewport, meaning limited options and scrolling content panels.
Thanks for the blog post, Adrian.
One of the biggest drawbacks of disclosure components in general is that collapsed content does not show up when you do browser search (cmd+F). These elements are often to organize documentation yjs). But by defaulting all disclosures to the closed state, all content inside them will not show up in when searching.
I suppose this issue could be skirted by adding an expand-all feature, which is probably good practice anyway, but it would be much nicer if you could just cmd+F as usual, and disclosures containing the search content would expand when you jumped to an instance of a search phrase contained inside it. Maybe there are other issues with this approach that I don’t know of?
I completely agree about how hidden content breaks in-page search. In my experience, when more than one chunk of collapsed content appears it is a sign of either poor information architecture or some misplaced notion of “simplifying” the page.
I have no idea why Wikipedia on mobile collapses everything, for example, since it makes it that much harder to find what I want.
Valid use cases for hiding content might be a transcript. Not everyone needs it nor wants it, and it can add to the difficulty of page in-page navigation for voice, keyboard, and screen reader users. But when you want the transcript, it being only one interaction away is nice.