Accordion

You click the “Track your return” link in an email. The shop opens the order page, scrolls down a bit… and shows a closed section called Returns. You click the title. Nothing. You click it again. Nothing. Finally you spot the tiny arrow on the right, click it, and the section opens, while the arrow keeps pointing down.

That’s four bugs in ten seconds, all in one of the “simplest” components on the web. Accordions hide content, and hidden content is where bugs hide too: in the state, the scroll position, links, search and screen readers. Let’s learn to find them.

What is an accordion?

An accordion is a vertical stack of sections, each with a header that opens or closes its content. Closed, you only see the headers, so a long page becomes a short, scannable list. Open, a section pushes the content below it down, like the bellows of an accordion.

One single open/close section is often called a disclosure (or “collapsible”, “expandable section”). An accordion is a group of them.

You’ll usually see accordions in:

• FAQ and help pages: How do I return an item? Can I change my address?
• Order and booking details: Delivery · Items · Payment · Returns.
• Product pages on mobile: Description · Size & fit · Shipping.
• Settings and filters: Price, Brand, Size in a shop’s filter panel; advanced options in a form.

Anatomy

How it differs from similar components

Component	What it does	Typical use
Accordion	Shows or hides sections in place; several can be visible	FAQ, order details
Tabs	Shows exactly one section at a time, labels side by side	Overview / Specs / Reviews
“Show more” link	Reveals the rest of one text block	Long product description
Dropdown	Opens a list to pick a value	Country, size
Modal / sheet	Opens content on top of the page	Confirmations, forms

Dev note: Names differ by platform

Designers say accordion, the HTML standard has <details> and <summary>, the WAI-ARIA guide calls one section a disclosure, SwiftUI calls it a DisclosureGroup, and Android developers talk about expandable list items. It’s the same idea: a header that shows or hides content.

Designs & variants

The look differs a lot between platforms, but every variant has a header, a state indicator and a panel. Try them all, with the mouse and with the keyboard (Tab, then Enter or Space).

Help · Orders

When will my order arrive?

Standard delivery takes 2–4 working days. You get a tracking link by email as soon as the parcel leaves our warehouse.

Can I change my address?

Yes, until the order is packed. Go to My orders, open the order and tap Change address.

How do I return an item?

You have 30 days. Start a return in My orders and print the free label, or show the QR code at a parcel shop.

Trail runner 2 · €129

Shipping

Free over €50. Express (next day) €6.90.

Returns

30 days, free label. Refund within 5 days of arrival.

Size & fit

Runs small. If you are between sizes, pick the larger one.

Order #4821

Details

StatusDelivered

Items3

• Desk lamp · €39.90
• LED bulb ×2 · €15.00
• Gift wrap · €0.00

Delivery address

Order details3 items · €54.90

Single or multiple open?

• Multiple open (the default on most platforms): each section opens and closes on its own. Best when users may want to compare sections or keep several open, like filters or order details.
• Single open (an “exclusive” accordion): opening one closes the others. It keeps the page short, but users can’t see two answers at once, and closing a long section above can move the section you just opened (more on that below).

Neither is wrong. The bug is when the product says one thing and the app does another, or when the two modes are mixed on similar pages.

Default open state

Decide, document and test which sections start open:

• All closed is common for FAQs: the questions are the content.
• First section open (or the most important one) helps users see that the sections open at all, and answers the most common question without a tap. On an order page, Delivery is often open.
• Remember the user’s choice only if the product asks for it. Then test that it really comes back after a reload, Back navigation and an app restart (state persistenceState persistenceWhether the app remembers what the user did after navigating away, rotating, or restarting.Open in glossary →).

When to use it

Accordions work well when:

• The page has many sections and users only need one or two of them (FAQs, help, order details).
• Each section has a clear, predictable title, so users can tell what’s inside without opening it.
• The content is secondary or reference material, and the screen is small.
• Users don’t need to compare content across sections at the same time.

Good and bad uses

How good accordions behave

Most accordion bugs are not about colors. They are about state, focus and scrolling. These are the rules to test against.

The indicator tells the truth

The chevron points down when closed and up when open (on iOS: right when closed, down when open). Whatever opens or closes a section (a tap, the keyboard, “Expand all”, a link, the default state on load) the chevron, the panel and the screen reader state must agree. A chevron that’s driven by its own variable instead of the real open state drifts out of sync quickly.

The whole header is the button

Users tap the title, not the arrow. The entire header row must react, with a touch targetTouch targetThe area of the screen that responds to a tap, which should be large enough for a finger.Open in glossary → of at least 44×44 pt on iOS and 48×48 dp on Android. A tiny chevron that’s the only clickable part fails users with shaky hands, and feels broken to everyone else.

Opening doesn’t lose your place

Opening and closing changes the height of the page, so things move. Test with long content:

• In single-open mode, opening a section below a long open section closes the long one. Everything moves up, and the header you just tapped can jump out of view. Good implementations keep the tapped header where it was.
• Code that “scrolls the new content into view” must scroll to the header, not to the end of the panel. Otherwise long panels push their own header off-screen.
• Closing a long section while you’re scrolled inside it should leave you on its header, not somewhere random further down the page.
• On the web, check that the page height update doesn’t make the browser’s scroll anchoring jump in odd ways, and on phones check rotation (reflowReflowContent rearranging into a single column at narrow widths or high zoom, without sideways scrolling.Open in glossary →).

Animation respects “Reduce motion”

A short height animation (about 200–300 ms) helps users see where the content came from. But users who turn on Reduce motion (iOS), Remove animations (Android) or prefers-reduced-motion (web) should get an instant change or a simple fade. Also check that fast double taps during the animation don’t leave the section half-open or out of sync with the chevron.

Deep links open the section

FAQ and help pages are full of links like shop.example.com/help#returns, and apps get deep linksDeep linkA link that opens a specific screen inside an app instead of just its home screen.Open in glossary → like shop://orders/4821/returns. The link must open the target section and scroll its header into view, both when the page loads and when the user clicks an in-page link. Scrolling to a closed header, or opening the section without scrolling to it, are both bugs.

Find in page and hidden content

Press Ctrl+F (Cmd+F on a Mac) and search for a word that’s inside a closed section. On most custom accordions, the browser finds nothing, because closed content is hidden. Users then think the answer doesn’t exist.

Dev note

Closed content is hidden with display: none.

Two web features help:

• Native <details>: Chrome, Edge and recent Firefox versions search inside closed <details> elements and open the one with the match. Safari added this later, so check it there too.
• hidden="until-found": a custom accordion can hide its panel this way. The browser can still search it and reveals the section (the page should then update its chevron). Chromium browsers and recent Firefox support it; Safari support is newer and partial at the time of writing, so test in your target browsers.
  Dev note

  The browser fires a beforematch event; the page should also update aria-expanded.

Common bugs

#	Bug	What you see	Severity
1	Chevron out of sync	Arrow points down while the section is open, or doesn’t turn after “Expand all”	Low–Medium
2	Only the arrow is clickable	Clicking the title does nothing	Medium
3	Scroll jump	After opening a section, its header is off-screen	Medium
4	Wrong screen reader state	VoiceOver says “collapsed” for an open section	High (for affected users)
5	Deep link lands on a closed section	#returns scrolls there but doesn’t open it	Medium
6	“Expand all” out of sync	The button says “Expand all” while everything is open	Low
7	Hidden content not searchable	Ctrl+F finds nothing that’s inside a closed section	Low–Medium
8	Content cut off	Long text, large fonts or a late image are clipped at a fixed height	Medium–High
9	Focus lost or trapped	After closing, focus jumps to the top; or links in a closed panel are still Tab stops	Medium
10	Double tap breaks it	Fast taps during the animation leave a half-open section	Low

Stress-test it

This is a correct accordion on a banking help page. Change the settings and watch what happens. Use the mouse, then only the keyboard.

Mode

SingleMultiple

Motion

AnimatedReduced

Closed content

HiddenUntil-found

Scroll fix

OffOn

Help · Cards

Answers to the questions we hear most about cards.

How do I freeze my card?

Open Cards, tap your card and switch on Freeze. Payments are blocked straight away. Switch it off to use the card again.

What are the fees abroad?

Paying by card in another currency is free on all plans. Cash withdrawals:

• Standard: 2 free per month, then 1.7%
• Plus: €400 per month free, then 1%
• Premium: unlimited free withdrawals

On weekends we add 0.5% to the exchange rate for most currencies, because markets are closed. Some ATMs charge their own fee. Always choose to be charged in the local currency: if the ATM converts for you, the rate is usually much worse.

Traveling for more than 3 months? Tell us in the app so we don't block your card for unusual activity.

Fees are shown in the transaction details right after each payment.

How do I order a new card?

Go to Cards › Order a new card. Standard delivery is free and takes 3–5 working days.

How does cashback work?

You get 1% back at partner shops. Enter the partner code BLUEFIN at checkout to get 2% for your first month.

Why was my payment declined?

• Your card is frozen or expired
• Not enough money in the account
• You reached your daily spending limit
• The shop needs 3-D Secure and the approval timed out
• Online payments are switched off in card settings

Can I set a spending limit?

Yes. Open Cards › Limits and set a daily or monthly amount.

How do I close my account?

Move your money out first, then go to Profile › Close account. It takes up to 5 working days.

Still need help?

Chat with us in the app, 24/7. Average reply time: 2 minutes.

Card issued by Example Bank. Fees as of October 2026.

…/help#declined Reset

Screen reader would say

Tab to a question or click one to hear it…

Event log

• Open and close questions, or use the link.

Things to try: in Single mode with the scroll fix Off, scroll down through the long “fees abroad” answer and tap the next question: the header you tapped jumps out of view. Turn the fix On and repeat. Then switch Closed content to Until-found, close everything and press Ctrl+F / Cmd+F to search for BLUEFIN (works in browsers that support it, like Chrome and Edge).

Find the bug

This order page in a web shop has an accordion with six bugs. Explore it like a tester:

• Click the titles, not just the arrows, and watch the arrows.
• Open the long Items section and look at where its header went.
• Use Expand all, then open and close sections by hand.
• Use the email link and the “See returns” link inside Delivery.
• Tab through the page and read the screen reader panel.

🐞 Bug hunt: Order #4821

This demo has 6 hidden bugs. Explore it like a tester, then check your findings.

Found0/6

shop.example.com/orders/4821

nordic·homeMy account

My orders ›

Order #4821

Delivered

Placed 3 Oct · 8 items · €174.50

Order details

Expand all

Delivery

Delivered Mon 6 Oct

Delivered on Monday 6 October at 14:12 to parcel locker “Hauptbahnhof 3”, compartment 41.

Something wrong with your order? See returns

Items (6)

8 pieces from 1 seller

Payment

Visa •••• 4242

Returns

Free returns until 5 Nov

Help with this order

Chat or call us

Tester tools

Reload page

Email link: …/orders/4821#returns

Screen reader would say

Tab to a control or click one to hear it…

1. 1

   Hint: Look at the Delivery section when the page loads. Then try Expand all.

   The chevron points the wrong way

   Delivery is open on load, but its arrow points down, and after a click it is closed with the arrow pointing up. Expand all opens every section without turning any arrow. The arrow is driven by its own variable instead of the real open state. Expected: down when closed, up when open, always.

   Reveal answer✓ I found this
2. 2

   Hint: Click a section title.

   Only the small arrow opens a section

   The header row is a plain div; only the 32 px chevron is a button. Clicking the title or the empty space does nothing. Expected: the whole header is the button, with a touch target of at least 44×44 pt / 48×48 dp.

   Reveal answer✓ I found this
3. 3

   Hint: Open the long Items section and look for its title.

   Opening Items scrolls its header out of view

   After opening, the page scrolls so the end of the panel is visible. For a long panel that pushes the header you just clicked off the top, so users lose their place. Expected: the header stays where it was (or is scrolled to the top), and the content opens below it.

   Reveal answer✓ I found this
4. 4

   Hint: Open a section, then Tab to its arrow and read the screen reader panel.

   Screen reader always says “collapsed”

   aria-expanded is hard-coded to false, so a screen reader announces “collapsed” for open sections too. The button is also outside the h3, so it isn’t read as a heading. Expected: aria-expanded follows the real state, and the button sits inside the heading.

   Reveal answer✓ I found this
5. 5

   Hint: Use the email link, or “See returns” inside Delivery.

   The #returns link doesn’t open Returns

   The URL changes to #returns and the page scrolls to the Returns header, but the section stays closed. Users who came for the return label see nothing. Expected: a deep link opens the target section and shows its header.

   Reveal answer✓ I found this
6. 6

   Hint: Open every section by hand, then look at the button. Or use Expand all and close them by hand.

   “Expand all” shows the wrong label

   The label is a separate true/false value that only the button itself flips. After opening all five sections manually it still says “Expand all”, and clicking it does nothing visible except change the label. Expected: the label is derived from the sections: “Collapse all” when all are open.

   Reveal answer✓ I found this

How to test it

Checklist

Accordion test checklist

0 of 13 checked

Copy

• The right sections are open on first load, as the design says
• Clicking or tapping anywhere on the header opens and closes the section
• The chevron always matches the state: on load, after taps, keyboard, Expand all and links
• Single vs multiple open works as specified, consistently across similar pages
• "Expand all / Collapse all" opens and closes everything, and its label matches the real state
• Opening and closing long sections keeps the tapped header in view (no scroll jumps)
• Long text, translations and the largest text size are never cut off inside a panel
• Deep links and in-page links (#returns) open the right section and scroll to its header
• Ctrl+F / Cmd+F finds text in closed sections (or the team has decided it does not need to)
• Animation is short, and instant with Reduce motion; fast double taps leave a clean state
• Keyboard: Tab reaches every header, Enter and Space toggle it, closed content is not a Tab stop
• Screen reader announces button, title, expanded / collapsed, and the heading level
• Open state survives Back navigation and rotation (if the product requires it)

Example test cases

Tools

• Elements panel in DevTools: click a header and watch aria-expanded change live in the DOM. If it never changes, you’ve found bug #4 without a screen reader.
• Accessibility pane / Lighthouse: shows the computed role, name and state of each header.
• Reduced motion on the web: DevTools › Cmd/Ctrl+Shift+P › “Emulate CSS prefers-reduced-motion”.
• Deep links: paste URLs with #section into a new tab; on Android use adb shell am start -a android.intent.action.VIEW -d "shop://orders/4821/returns", on the iOS Simulator xcrun simctl openurl booted "shop://orders/4821/returns".

Accessibility

• Button inside a heading (web). The heading lets screen readerScreen readerSoftware that reads the screen aloud for blind and low-vision users, like VoiceOver or TalkBack.Open in glossary → users jump between sections; the button makes it focusable and clickable.
  Dev note

  The ARIA accordion pattern puts a real <button> inside a heading (<h3><button aria-expanded="false" aria-controls="panel-id">Returns</button></h3>); ARIAARIAHTML attributes that tell assistive technology what custom elements are and what state they're in.Open in glossary → attributes carry the state.
• aria-expanded must follow the state. true when open, false when closed. Put it on the button, not on the panel or a wrapper div.
  Dev note

  aria-controls points to the panel’s id. Panels can be a role="region" labeled by their header, but with many panels that creates noise, so it’s optional.
• Native <details> / <summary> gets all of this for free: focusable, Enter/Space to toggle, state announced. Check that custom styling didn’t remove the focus ring.
• KeyboardKeyboard navigationUsing a website with only the keyboard: Tab to move, Enter or Space to activate, Esc to close.Open in glossary →. Tab moves between headers and into open panels, Enter or Space toggles. Links inside closed panels must not be reachable with Tab. After closing, focus stays on the header (focus orderFocus orderThe order in which the Tab key moves through interactive elements.Open in glossary →).
• Mobile. On iOS, VoiceOver should announce the expanded or collapsed state; on Android, TalkBack announces “expanded” / “collapsed” and offers expand / collapse actions when the app sets them. Custom rows that only change an icon announce nothing.
• Don’t rely on the arrow alone. The open section should also be visible from its content, and the chevron needs 3:1 contrast against its background.

Mobile vs web

iOSAndroidWeb

• The chevron points right when closed and turns down when open.
  Dev note

  SwiftUI has DisclosureGroup (and OutlineGroup / lists with children for trees); UIKit lists use an outline disclosure accessory.
• Common in Settings-style lists, sidebars and forms. Multiple sections can be open.
• Test VoiceOver (state and hint), Reduce Motion, the largest Dynamic Type size (long titles must wrap, not truncate) and the iPad sidebar.

• Material 3 has no official accordion component. Apps build expandable list items or cards.
  Dev note

  With an expand_more icon; older apps use ExpandableListView.
• Test that TalkBack says “expanded” / “collapsed”.
  Dev note

  In Jetpack Compose, the expanded state should be exposed to TalkBack (state description and expand / collapse actions).
• Check rotation and process death: does the open section survive? Test Remove animations in Accessibility settings and the largest font size and display size.

• Inspect the headers in DevTools.
  Dev note

  Prefer <details>/<summary> or the ARIA accordion pattern (heading + button + aria-expanded).
• Test #anchors and deep links, Ctrl+F, browser Back after following a link, and 200% zoom.
• Check what happens when JavaScript is slow or fails: is the content still reachable, or stuck closed? And for SEO pages, is the content in the HTML or fetched on open?

Check your understanding

Quick quiz

0/5 answered · 0 correct

1. 1.A section is open, but VoiceOver says "Payment, button, collapsed". What is the most likely cause?

   AThe animation is too slowBaria-expanded is not updatedCThe heading level is wrongDThe chevron icon is missing

2. 2.Which is the best place for an accordion?

   AThe total price on a checkout pageBA help page with 15 questionsCTwo short sentences of textDAn error message after saving

3. 3.A link to /help#returns scrolls to the Returns header, but the section stays closed. Is this a bug?

   AYes, a deep link should open the section it points toBNo, the user can open itCOnly on mobileDOnly if the page is slow

4. 4.In single-open mode, you tap a section below a long open section and the tapped header disappears off the top. Why?

   AThe section was cut off by a max-heightBThe long section above closed and the page moved upCThe browser cache was fullDThe chevron rotated the wrong way

5. 5.What does hidden="until-found" do?

   AHides content from screen readers foreverBLets find-in-page search hidden content and open itCLazy-loads the content from the serverDAnimates the panel height

Key takeaways

• An accordion is a stack of headers that show or hide content in place. Use it for lots of optional detail, never to hide prices, fees or errors.
• The whole header is the button, and the chevron, panel and aria-expanded must always agree.
• Test long content: scroll jumps in single-open mode, panels scrolled to the end, text cut off at a fixed height.
• Deep links must open the section they point to, and closed content should still be findable (<details>, hidden="until-found").
• Always test with the keyboard, a screen reader, Reduce motion and the largest text size.