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.

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 prototyped on Codepen.

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


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



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.


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

Leave a Comment or 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>