Accordions: when collapsing content helps people read

Collapse content into an accordion when people will only need a few parts of the page, each part stands on its own and every block’s heading says what’s inside. If they’ll read nearly everything, or the text is short, leave it open (NN/g, Accordions on Desktop). In code, the HTML pair <details> and <summary> already opens and closes without any script (MDN, the details element).

What counts as an accordion

An accordion is a block that shows only a heading and reveals its content when someone clicks it. It has three pieces: the heading, an icon that shows whether it’s open or closed and the panel holding the hidden content (NN/g).

What sets it apart from a window on top is where the content shows up. An accordion opens in the flow of the page and pushes everything below it down, without covering anything (NN/g, Accordions on Mobile).

When collapsing helps

NN/g’s 2023 article lists the cases where an accordion pays off (NN/g):

People want only a few parts. If they’ll skip almost everything, hiding the rest saves them time.
The task follows steps. A multistep checkout shows only the current step and opens the next one once the previous step is complete.
The parts are independent. FAQ pages and product details belong here, since nobody needs two sections side by side.
The screen is small and the text is long. On a phone, collapsing keeps the page at a length people can actually get through.

On mobile, the biggest gain is the overview. Closed headings act as a table of contents, so people see at a glance what the page holds before picking where to go (NN/g). Without that, they scroll, don’t find it and leave, even when the answer was further down.

When collapsing gets in the way

The same source points to the cases where it’s better to show everything (NN/g):

People need most of the content. Opening block after block turns into work, and a long page ends up cheaper.
There isn’t much content. With everything closed, the page looks empty and suggests there’s nothing useful on it.
The hierarchy runs deep. Accordions inside accordions make people lose their place. Tabs or a side menu work better.
The content won’t fit in a heading. If you can’t sum up a block in a few words, nobody knows whether it’s worth opening.
It’s meant to be read start to finish. News stories and narratives lose their thread when they’re chopped into blocks.

Some costs show up in every case. Each block people open asks them to look, decide and click. Whatever stays closed can go unnoticed. And a printed page comes out with the blocks closed, unless the site opens them all before printing (NN/g).

The cue that a block opens

A bare heading looks like a link to another page. In 2020, NN/g tested this with 136 people on phones, using menus with four icon options and one version with no icon (NN/g, Accordion Icons). The downward caret, which flips when the block opens, was the safest choice.

With no icon, or with a made-up one, people expected to leave the page. The plus sign and the right-facing arrow did no better than having no icon on that point (NN/g).

The same study showed taps split between the text and the icon. Even with the caret, 29% of taps landed on the text (NN/g). So text and icon have to do the same thing. Making the text go to another page while the icon opens the block misleads whoever taps.

What the code needs to do

<details> handles the basics. The open attribute sets whether the block starts open. The name attribute groups blocks that share a name so only one of them stays open (MDN).

If you build the accordion out of other elements, you have to redo what the browser would hand you for free. The W3C pattern asks for each block’s heading to be a button inside a heading of the right level. The button reports its state in aria-expanded and opens with Enter or Space (W3C, Accordion Pattern).

Find in page is another issue. In a typical accordion, closed text doesn’t show up in the browser’s find in page, and a link to a passage inside it doesn’t work. Since Chrome 102, the hidden="until-found" attribute lets the browser find that text and open the block on its own (Chrome for Developers, hidden=until-found). The same page warns that the block still has to open on click, because not every browser supports the attribute.

On mobile: the Back button

One problem that’s specific to phones is disorientation. When the site scrolls the open block up to the top, people think they’ve moved to a new page. They tap Back to close it and leave the whole page instead (NN/g).

NN/g suggests two ways out. One is to treat opening a block like an in-page link, so Back closes it. The other is not to scroll at all when it opens. For very long blocks, a heading that sticks to the top while people scroll lets them close it without going all the way back up (NN/g). In the testing the article describes, nobody understood a button labeled “Collapse”.

How I did it on kahue.net

On my about page, three blocks start closed: the rest of my certifications, my earlier experience and my education and languages. The three most recent roles show up open. Reference material stays collapsed, and what people read first stays in view.

Each closed bar says what’s inside without having to open it. The credentials bar shows “51 certificates and courses”, and the experience bar shows “2015-2024 · 10 roles”. The year range comes from the data itself, so it updates when a new role goes in.

I used <details> and <summary> on purpose. The blocks open without JavaScript, and the closed content stays in the HTML, so search engines and résumé readers get all of it. The bar has a background, a shadow and a downward caret in the accent color that flips when it opens. I did it that way because a loose line of text doesn’t show that you can click it.

JavaScript only steps in for two things the element can’t do alone. A link that arrives with a block’s address, like #experiencia-anterior, opens that block. And before printing, every block opens, so the PDF doesn’t come out cut short. The blocks have no name, so you can open several at once.

Going by NN/g’s list, an expand all button is missing. Compared with the W3C pattern, the order is reversed: the education <h2> sits inside the <summary>, instead of the button sitting inside the heading.

Where the sources disagree

NN/g itself changes its tone depending on the screen. The 2015 piece on mobile calls accordions one of the most useful elements there (NN/g). The 2023 piece on desktop says they’re not always recommended and lists more cases against than for (NN/g).

The icon is another split. The 2023 article says the caret and the plus work best (NN/g). The 2020 study found the plus doesn’t beat having no icon (NN/g). The caret is where both agree.

Last, there’s the group where only one block opens. MDN presents the name attribute as the way to build accordions without scripting (MDN). NN/g asks that people be able to open several at once, because closing one automatically keeps them from comparing two blocks (NN/g). The feature exists, but whether to use it depends on the task.

The common mistake: hiding what people came for

The most frequent slip is collapsing the very information that matters most. NN/g’s example is a US government site that tucked its face mask rules inside a closed block (NN/g). The text was short and would have fit open on the page.

The question that sorts the cases is simple. If almost everyone who arrives needs it, leave it open. An accordion is for what only some people are looking for, like the answers on an FAQ page.