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.

…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.

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.

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:

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>.

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.

10 Comments

Reply

Do details/summary pass as disclosure widgets?

Matthew Kreiling; . Permalink
In response to Matthew Kreiling. Reply

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 <details> / <summary>.

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.

Reply

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!

Reply

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 details widgets is the inconsistency in how different browsers and screen readers implement the summary element and support headings as children of summary. The HTML specs don’t help much, because while the implicit role of summary is button, summary can 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.

Peter Weil; . Permalink
In response to Peter Weil. Reply

[…] 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 <details> / <summary> is lacking. The accordion pattern also should not extend outside the viewport, meaning limited options and scrolling content panels.

Reply

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?

In response to Danny. Reply

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.

Reply

Friendly heads up, it does look as though details & summary is now supported on Edge as of version 90 released in April 2021: https://caniuse.com/?search=details

Jean Ducrot; . Permalink
In response to Jean Ducrot. Reply

I failed to follow up on this post. In the JavaScript Required section I was talking about Legacy Edge versus Chromium Edge. I have updated that section.

Chromium Edge has supported <details>/<summary> since its first release (because Chromium supported it), pushing that back to January 2020 for the first official release.

Legacy Edge (now effectively extinct in the wild) will never support it.

Thanks for the nudge.

Reply

Tables of content are for the audience, accordions are about who they’re from.

In response to Peter Weil. Reply
[…] 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.

Leave a Reply to Adrian Roselli Cancel response

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>