Design an accordion

Requirements: what an accordion is for, and when not to use one

An accordion is a vertical stack of headers. Each header is a button that shows or hides the content under it, called its panel. Closed, the page is a short list of titles. Open, one or more panels push the content below them down the page.

It is often the first component in a design system interview because it looks trivial: a list, a boolean per item, a click handler. The interviewer is checking whether you see what that boolean costs. Content behind a click is content some people never read, cannot search, and cannot print. A senior answer starts with that question before it gets to the code.

When an accordion is the wrong tool

An accordion saves vertical space by hiding text. That is a good trade when people come for one or two items out of many, and a bad one when they need most of it. Nielsen Norman Group's guidance says the same: accordions help when users need only a few pieces of a long page, especially on small screens. When users need most or all of the content, show it, because every expand adds interaction cost and hides text from view.

• People need most of the content. A checkout's terms, a short policy page, or a recipe's ingredients. Hiding them adds a click per section and hides what users must read. Use a normal page with headings.
• People search with Ctrl+F or Cmd+F. Classic accordions hide panels with display: none, and the browser's find-in-page skips text that isn't rendered. A support page where nothing is findable is a real failure. We fix this later with hidden="until-found", but it is a reason to think twice.
• People print or save as PDF. Closed panels don't print. A policy page printed for a lawyer comes out as a list of questions with no answers, unless print CSS opens them.
• The sections are parallel views of one thing. Overview, Reviews and Specs of one product are alternatives you switch between: that is tabs. Tabs show one panel and keep the rest of the layout still. An accordion lets several panels be open at once and moves everything below.
• The page is long but linear. A long article with a table of contents and anchor links keeps everything readable, printable and findable, and still lets people jump. That beats an accordion for documentation.

Questions to ask the interviewer

Functional requirements

• Click or press Enter or Space on a header to toggle its panel.
• Two modes: single (opening one closes the others) and multiple. In single mode, an option decides whether the open panel can be closed, leaving all closed.
• Controlled and uncontrolled: the parent can own the open items, or just give defaults.
• Disabled items that can't be toggled but still read their title.
• A link such as /help#refunds opens and scrolls to that item.
• Text in closed panels is found by the browser's find-in-page, where the browser supports it.

Non-functional requirements

• Accessible: works with keyboard alone and announces expanded or collapsed with screen readers (NVDA, JAWS, VoiceOver, TalkBack).
• Fast: a toggle responds within one frame and keeps Interaction to Next Paint (INP) well under the 200 ms good threshold. Opening animates in 150 to 250 ms.
• Stable: no layout shift on load; Cumulative Layout Shift (CLS) contribution of 0 from the accordion.
• Small: under about 3 KB of JavaScript gzipped for the component itself, and working HTML before hydration.

Out of scope: drag to reorder items, a virtualized accordion with thousands of items (that is a tree or a list problem), and sections that save their open state to the server per user.

What makes a simple accordion hard

Here is the parts list. Every accordion item has a header (a heading element that holds the toggle button), a trigger (the button itself, with the title and a chevron icon), and a panel (the content). The root wraps all items and owns the rule for which ones are open.

Four properties of this component drive every decision in the rest of the guide.

1. It hides content. Whatever we use to hide a panel decides whether screen readers, find-in-page, search engines and print can see it. Hiding is the whole job, so the hiding method is the most important decision, not a detail.
2. It changes the page height. Opening a 400 pixel panel moves everything below it by 400 pixels. That is expected after a click, but the same move during page load is layout shift, and the same move with no animation is jarring. Animating it hits a CSS limit: height: auto can't be transitioned in most browsers today.
3. Its state lives in more than one place. The open items can belong to the component, to the parent page, or to the URL hash. A link from a support email must open the right answer. The API must allow all three without three components.
4. It is used everywhere, by teams you don't talk to. A FAQ, filters, a settings form, nested sections in docs. A design system component gets one chance at its API and markup, because every change after that breaks someone.

Notice what isn't on the list: performance at scale. An accordion has 3 to 30 items. Rendering cost is tiny unless panels contain heavy content, and that becomes a loading question (fetch on first open), not a rendering one.

Semantics: a button in a heading, or details and summary

The markup decides what a screen reader user hears and what a keyboard user can do. Get it right and most accessibility comes for free. Get it wrong and no amount of ARIA added later fixes it cleanly. The aria-patterns lesson covers the APG patterns in general; here we apply the accordion one.

<h3 class="acc-header">
  <button type="button" id="acc-shipping-trigger"
    aria-expanded="false" aria-controls="acc-shipping-panel">
    Shipping
    <svg aria-hidden="true" class="acc-chevron">...</svg>
  </button>
</h3>
<div id="acc-shipping-panel" hidden="until-found">
  <p>Orders ship in 2 business days.</p>
</div>

The details that matter in the APG pattern

• The heading level is a prop. A FAQ under an h2 page section needs h3 items; the same component in a sidebar under an h3 needs h4. Hardcoding h3 breaks the page outline. Expose headingLevel with a default of 3.
• Only the button is inside the heading. No extra links or menus in the header row: a heading with two interactive controls confuses both the outline and the click target. If an item needs actions (such as Delete), put them next to the heading, not inside the button.
• aria-expanded lives on the button, not the panel. Screen readers announce it when the button gets focus: "Returns, button, expanded".
• aria-controls is a hint. Of the major screen readers, mainly JAWS does anything with it. Keep it, since it is cheap and correct, but don't count on it.
• role="region" only for few panels. A region with a name becomes a landmark. The APG advises against it when more than about 6 panels can be open at once, because 25 FAQ landmarks bury the page's real landmarks. Our component adds it automatically when there are 6 items or fewer, and a prop overrides that.
• The chevron is decoration. Mark it aria-hidden="true"; the expanded state already carries the meaning. Rotate it with CSS from the aria-expanded attribute so the visual and the announced state can't drift apart.
• A panel that can't close says so. In single mode where one item must stay open, the open item's button gets aria-disabled="true". Not the disabled attribute: that removes it from the Tab order and users lose their place.

When native details is the better choice

The name attribute on details arrived in Chrome and Edge 120, Safari 17.2 and Firefox 130, so exclusive accordions now work with plain HTML in all current browsers. The ::details-content pseudo-element, which lets you style and animate the content part, followed in Chrome 131, Safari 18.4 and Firefox 143. On older versions both degrade safely: items just stop closing each other, or open without animation.

So for static content with no special rules, details is less code and works before JavaScript loads. Its limits are the ones listed above: no forced open item, the heading question, and state owned by the browser. A common middle ground in design systems is to render details in a CMS rich text renderer and the APG component in the app.

Open state, keyboard, and the component API

Two rules describe how items open. The type says how many can be open: single (at most one) or multiple (any number). In single mode, collapsible says whether the open item can be closed, leaving none open. A product page often wants single and not collapsible, so one section is always showing; a FAQ wants multiple.

What the open state looks like

The naive state is a boolean per item, kept inside each item. It breaks at the first real requirement: single mode needs an item to close its siblings, which it can't see. A deep link needs the root to open an item by name, and "Expand all" needs one place to set everything.

So the state lives in the root, as the list of open item values: a string in single mode (empty string for none), an array of strings in multiple mode.

Why item values and not indexes? Indexes shift when a CMS editor adds a question at the top, and then a saved or linked open state points at the wrong item. A stable string such as "refunds" survives reordering, reads well in a URL hash, and gives the element ids for free.

type Common = {
  headingLevel?: 2 | 3 | 4 | 5 | 6;
  disabled?: boolean;
  children: React.ReactNode;
};
type SingleProps = Common & {
  type: "single";
  value?: string;            // controlled ("" = none open)
  defaultValue?: string;     // uncontrolled
  onValueChange?: (value: string) => void;
  collapsible?: boolean;     // default true
};
type MultipleProps = Common & {
  type: "multiple";
  value?: string[];
  defaultValue?: string[];
  onValueChange?: (value: string[]) => void;
};
export type AccordionProps = SingleProps | MultipleProps;
// Usage: <Accordion type="single" defaultValue="shipping">
//          <AccordionItem value="shipping" title="Shipping">...

The API is compound: Accordion, AccordionItem, AccordionTrigger and AccordionPanel, sharing state through React context. A config array (items={[{ title, body }]}) looks simpler, but the first team that needs a badge in one header or a form in one panel is stuck. Compound parts keep each piece open to plain JSX.

Keyboard: Tab, Enter and Space, and no arrow keys

Unlike tabs, where the tab list is one Tab stop and arrows move inside it (roving focus, covered in the tabs guide), every accordion header is its own Tab stop. That's simpler and correct: Tab and Shift+Tab move between headers and into open panels, Enter and Space toggle. A FAQ with 24 items has 24 Tab stops, which is fine because users usually want the content in between.

Until April 2026 the APG listed Up, Down, Home and End as optional keys that move focus between headers. It removed them after testers reported the problem: with focus on a header, Down Arrow jumped to the next header instead of scrolling, so users couldn't read the panel they had just opened.

Screen reader users already jump between headers with the H key, because each one is a real heading. So the design system doesn't add arrow keys, and keeps aria-disabled headers (the locked open one) in the Tab order. The keyboard-navigation lesson has the general rules.

Animating height: the classic problem

Design asks for panels that slide open in about 200 ms instead of snapping. The naive CSS is height: 0 when closed, height: auto when open, and transition: height 200ms. It does nothing: the panel snaps. CSS transitions interpolate between two numbers, and auto isn't a number until layout computes it, so for most of CSS's history browsers simply refused to animate it.

There are four families of fixes. They differ in browser support, how much JavaScript they need, and what happens when a user clicks again halfway through an animation, which real users do all the time.

.acc-panel {
  grid-template-rows: 0fr;
  transition: grid-template-rows 200ms ease-out;
}
.acc-panel:not([hidden]) { display: grid; }
.acc-panel[data-state="open"] { grid-template-rows: 1fr; }
.acc-panel > .acc-inner {
  min-height: 0;      /* lets the row shrink below the content */
  overflow: hidden;
}
.acc-chevron { transition: rotate 200ms ease-out; }
[aria-expanded="true"] .acc-chevron { rotate: 180deg; }

@media (prefers-reduced-motion: reduce) {
  .acc-panel, .acc-chevron { transition: none; }
}

Four states, not two

Animating forces a small state machine. Open and closed aren't enough: while closing, the panel must still be rendered so the transition can play, and only at the end may it become hidden. Model it as four states.

• closed: hidden (or hidden="until-found") is set; data-state="closed".
• opening: remove hidden, wait one frame so the 0fr row is painted, then set data-state="open" so the transition runs. On transitionend, go to open.
• open: nothing to do. Content can grow freely because the row is 1fr.
• closing: set data-state="closed" (row goes to 0fr). On transitionend for grid-template-rows, set hidden. If the user clicks again first, go back to opening: the transition reverses from where it is.

Cost. Animating height or grid rows runs layout on every frame, and moves everything below the panel. On a normal page, layout for one accordion takes a millisecond or two, well inside the 16.7 ms frame at 60 Hz.

The cheaper-looking transform: scaleY() avoids layout but squashes the text while it moves and leaves a gap below, so it looks wrong. Keep the duration at 150 to 250 ms; long animations make a page feel slow and push users toward the reduced motion setting. The visual-accessibility lesson explains who turns it on and why.

What happens to closed panels: hiding, find-in-page, lazy content

A closed panel can be removed from the DOM, kept but hidden, or kept but hidden in a way the browser can still search. The tabs guide compares every hiding technique in a table; this chapter applies the same rules to the accordion, where the stakes are higher. A FAQ's whole value is its text, and that text is closed most of the time.

Support for hidden="until-found" and beforematch: Chromium since version 102 (2022), Firefox since 139 (2025), Safari since 26.2 (late 2025). MDN notes that Firefox before 148 and Safari 26.2 don't scroll to the match correctly, so test it there.

function useFindable(ref: React.RefObject<HTMLDivElement>, value: string, phase: PanelPhase) {
  const { open } = useAccordionContext();
  useLayoutEffect(() => {
    const el = ref.current;
    // React only writes hidden="" (a boolean), so set the until-found value here
    if (el && phase === "closed") el.setAttribute("hidden", "until-found");
  }, [ref, phase]);
  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const onMatch = () => open(value, { animate: false });
    el.addEventListener("beforematch", onMatch);
    return () => el.removeEventListener("beforematch", onMatch);
  }, [ref, value, open]);
}

Note animate: false. The browser scrolls to the match right after beforematch; if the panel then grows over 200 ms, the match slides away from where the browser scrolled. Opens triggered by find-in-page or a deep link skip the animation. Only clicks animate.

In single mode, a find match in a closed item closes the open one. That's correct: the root's rule still holds, and the user sees the panel with their match.

Lazy content: fetch on first open, keep it after

Most panels hold static text, so it should be in the HTML. Some don't. The product page's Shipping panel shows a delivery estimate for the user's postcode from GET /api/shipping-estimate, about 120 ms at the median and 800 ms on a slow phone connection. Fetching it for every product view wastes a request on every visitor who never opens the panel, which on a typical product page is most of them.

• Fetch on first open. The panel mounts its content the first time it opens and remembers that it has opened (hasOpened in a ref). After that it stays mounted and hidden, so closing and reopening doesn't refetch or lose the spinner's place.
• Start early. Begin the request on pointerenter or focus of the header. The gap between pointing at a header and clicking it is often a few hundred milliseconds, enough to hide much or all of a 120 ms request.
• Show a skeleton with a fixed height. The panel animates open to the skeleton's height, then grows a little when data arrives, instead of animating to 0 and jumping.
• Handle failure inside the panel. Show a short message and a Retry button in the panel, and keep the header working. A failed estimate must not break the accordion.
• Cache by key. Use the app's server cache (React Query, SWR, or the router's loader cache) keyed by product and postcode, so the second product page with the same postcode is instant.

Deep links: opening the panel named in the URL

Support emails a customer https://shop.example/help#refunds. The page must load with the Refunds answer open and on screen, below the site's 64 pixel sticky header, not hidden under it. The url-as-state lesson covers the URL in general; here are the accordion's details.

The naive version reads location.hash in a useEffect and opens the item. Two things go wrong. The effect runs after hydration, which on a mid-range phone can be 2 to 4 seconds after the HTML is painted, so the user sees a closed FAQ, starts reading, and then everything below Refunds jumps down. That is layout shift the user didn't cause, and it counts against CLS.

The second problem is scrolling. The browser tried to scroll to the #refunds target during load, while it was still hidden, so after the late open the answer can sit half off the screen until the effect scrolls again.

Scrolling with a sticky header

Browsers scroll a fragment target to the very top of the viewport, right under a sticky site header that covers it. CSS fixes it without JavaScript: scroll-margin-top on the target tells every scroll into view, native or scrollIntoView(), to leave that much room. Since our target is inside the panel, the margin must also leave room for the item's own header.

:root {
  --site-header-h: 64px;
  --acc-header-h: 56px;
}
.acc-inner[id] {
  /* sticky site header + this item's header + breathing room */
  scroll-margin-top: calc(var(--site-header-h) + var(--acc-header-h) + 8px);
}

Writing the hash when a user opens an item

• Opt in. Only the help page wants the URL to follow the accordion. A syncHash prop (or the page using the controlled API) turns it on; filter groups never touch the URL.
• Replace, don't push. Use history.replaceState(null, "", "#refunds"). Pushing would make the Back button step through every question the user opened, and setting location.hash also scrolls the page.
• Listen for hashchange. An answer that says "see Refunds" links to #refunds on the same page. The root listens and opens that item, without animation, then scrolls to it.
• Multiple mode. A hash names one place. In multiple mode, write the most recently opened item, and clear it when that item closes.

Architecture, data model, server rendering and nesting

Time to put the decisions together. The component is four parts that share one context, plus three small hooks that other design system components already use or can reuse.

Data moves in a loop. The server renders HTML with default items open. The user clicks, the trigger asks the root to toggle, and the root computes the next value and either stores it or hands it to the parent through onValueChange.

The new value flows down as props, and each panel runs its animation. Lazy panels call the server cache on first open; the hash hook writes the URL. Nothing else talks to the network.

type PanelPhase = "closed" | "opening" | "open" | "closing";

type AccordionState = {
  type: "single" | "multiple";
  value: string[];             // single mode stores 0 or 1 entries internally
  collapsible: boolean;
};

type ItemContext = {
  value: string;               // stable: "refunds", never an index
  isOpen: boolean;             // derived: state.value.includes(value)
  disabled: boolean;
  triggerId: string;           // `${rootId}-${value}-trigger`, rootId from useId()
  panelId: string;
  headingLevel: 2 | 3 | 4 | 5 | 6;
};

type PanelState = { phase: PanelPhase; hasOpened: boolean }; // per panel, local

useId() gives an id prefix that matches between server and client, so aria-controls and aria-labelledby survive hydration without warnings. Combining it with the item's value keeps ids readable in the DOM and unique when two accordions on the page both have a "shipping" item.

Server rendering without layout shift

• Render the real starting state on the server. Items in defaultValue come out with aria-expanded="true" and no hidden; closed items come out hidden. The first paint is already the final layout.
• Make closed panels findable before hydration. React renders hidden as a boolean (hidden=""), so the server HTML has plain hidden, and find-in-page and deep links can't reveal anything until the layout effect upgrades it. A few lines of inline script right after the accordion's HTML can set hidden="until-found" on its closed panels during parsing. Hydration accepts that, because React only checks that a boolean attribute is present.
• Don't measure on mount. The grid technique needs no height numbers, so hydration does no layout reads. A scrollHeight-based panel that renders closed on the server and measures on the client is a common source of a one-frame flash.
• Never decide the open state on the client from client-only data. "Remember which sections were open" from localStorage means the server renders one layout and the client switches to another: a jump. Store it in a cookie so the server can render it, or don't remember it.
• Before hydration, headers don't toggle. On a slow phone that window can be a few seconds. For most pages that's fine because the content is readable and findable. For a no-JavaScript requirement, render native details instead. The ssr lesson covers the hydration gap in general.

Nested accordions

Docs and settings pages nest accordions: a Billing section with Invoices and Payment methods inside. Four things to get right:

• Heading levels step down. The inner root reads the outer item's level from context and defaults to one more: h3 items inside contain h4 items.
• Each root is its own scope. The inner Accordion creates a new context, so inner items never register with the outer root, and the outer root's rules (single mode, Expand all) never reach inner items.
• Heights keep working. With grid rows, the outer row is 1fr, so it grows when an inner panel opens. With fixed pixel heights from measuring, the outer panel would clip the inner one: another reason for the grid technique.
• Find-in-page reveals the whole chain. A match in a closed inner panel inside a closed outer panel reveals both: the browser fires beforematch on each until-found ancestor, and each item opens itself in state.

Testing and the last quality checks

A design system component is tested by its contract: what users and assistive technology see, not internal state. Write tests against roles and attributes, the same things a screen reader reads. Then test the browser-only behaviour (animation, find-in-page, scrolling) in a real browser, because jsdom has no layout and no find-in-page.

test("single, not collapsible: opening one closes the other", async () => {
  const user = userEvent.setup();
  render(<Faq type="single" collapsible={false} defaultValue="shipping" />);
  const shipping = screen.getByRole("button", { name: "Shipping" });
  const returns = screen.getByRole("button", { name: "Returns" });
  expect(shipping).toHaveAttribute("aria-disabled", "true");

  returns.focus();
  await user.keyboard("{Enter}");
  expect(returns).toHaveAttribute("aria-expanded", "true");
  expect(shipping).toHaveAttribute("aria-expanded", "false");
});

test("beforematch opens the item in state", () => {
  render(<Faq type="multiple" />);
  const panel = document.getElementById(screen.getByRole("button", { name: "Refunds" })
    .getAttribute("aria-controls")!)!;
  act(() => { panel.dispatchEvent(new Event("beforematch")); });
  expect(screen.getByRole("button", { name: "Refunds" })).toHaveAttribute("aria-expanded", "true");
});

Two checks people forget. First, zoom to 400 percent at a 1280 pixel window (WCAG reflow): long header titles must wrap, not clip, and the chevron must stay next to the text. Second, a page with two accordions that share item values: the ids must still be unique, which the useId prefix guarantees and a unit test can assert by counting duplicate ids in the document.

Running it in the interview

This is a 30 minute question, and the trap is spending 20 of them on a toggle. Show early that you know where the real decisions are, then go deep on two or three of them.

Say the reasons out loud. "I'm using hidden=\"until-found\" because people search FAQ pages with Ctrl+F" earns more credit than the attribute alone. Interviewers grade the trade-off, not the trivia.

Follow-ups to expect