Accordion: Progressive Disclosure Rules and Examples

An accordion is a grouped set of labelled disclosure controls that lets a reader reveal or collapse supporting content in place. Use it for optional reference detail, not for the page’s main answer.

This rendered pair demonstrates progressive disclosure: the labels remain scannable, one panel is open, and both answers are present in the page’s HTML whether or not a visitor interacts.

Why this element matters

Progressive disclosure means showing the information needed for the current decision while keeping deeper or less common detail available on demand. It helps when a page serves readers with different levels of knowledge. A returning customer can scan past implementation notes; a first-time user can open them. The control lowers visual density without deleting content or forcing every reader through every exception.

The same convenience can become concealment. A reader who searches for a direct answer, lands on the page, and sees eight closed labels must guess which panel contains it and perform an extra action. On mobile, repeated opening and closing also moves content around the viewport. The accordion therefore earns its place only when most readers can complete their primary task without opening every panel.

Machine extractability adds a stricter test. Extractability is the ability of search engines, AI answer systems, parsers, and assistive tools to receive the text and preserve its relationship to its label. Every answer must be present in the initial server-rendered Document Object Model (DOM), the browser’s structured representation of the page. CSS may visually collapse a present panel; JavaScript must not fetch or manufacture the answer only after a click. A crawler may never click, execute the client code, or wait for a secondary request.

Follow the element writing rules before using this pattern. If the content’s purpose matches a more specific typed element, that element takes precedence. An accordion can contain permitted supporting content, but it must not rename or flatten a warning, comparison, definition, or step sequence merely to make the page shorter.

When to use it

Use an accordion when all four conditions are true:

1. The reader can predict the panel’s content from its label.
2. The content is useful to a subset of readers rather than necessary to everyone.
3. All panel content ships in the initial HTML and remains reachable without a pointer device.
4. Collapsing materially improves scanning on the expected viewport.

Good candidates include optional compatibility details, uncommon error branches, supporting definitions, secondary policy clauses, shipping exceptions, and grouped reference answers. An accordion can also work for a large FAQ collection when every question remains visible and each answer is self-contained.

Near misses expose the most common misuse:

• A short page with two brief sections: visible headings and paragraphs are faster to scan than two controls.
• A long article made to look shorter: collapsing ten substantial sections reduces perceived height but increases interaction and hides the page’s scope.
• Primary product information: price, availability, material limitations, cancellation terms, and core specifications influence the decision and must not depend on expansion.
• A sequential procedure: steps require order and context. A closed panel can make readers skip a prerequisite or execute steps out of sequence.
• A comparison: readers need simultaneous visibility across the same criteria. Separate panels force memory-based comparison.
• A safety warning or legal qualification: the consequence of missing it is higher than the visual benefit of hiding it.
• A navigation substitute: an accordion is not a table of contents. It reveals content at the same location rather than moving to stable page sections.

When uncertain, publish the content visibly. Extra scrolling is usually recoverable; a missed answer, undisclosed constraint, or unavailable DOM node is not.

Ready to Monitor Your AI Visibility?

Track how AI chatbots mention your brand across ChatGPT, Perplexity, and other platforms.

Get Started Contact

Where to place it

Place the accordion after the page has delivered its direct answer and enough visible explanation for the reader to understand what the group contains. Introduce it with an H2 and one scope sentence. The group then behaves as a supplementary reference layer within that section.

Exact position rules:

• Put it after the visible explanation it qualifies, never between a claim and the evidence supporting that claim.
• Keep it within the parent section whose subject labels every item. If the labels make sense only with a missing heading, the group is misplaced.
• Place a product-detail accordion after the core value, price context, and purchase conditions; place troubleshooting branches after the shared diagnosis and safest first check.
• Keep a closing FAQ accordion after the main conclusion and before the final next action, provided it answers residual rather than repeated questions.
• Give the group a stable section anchor when readers may link to it. Individual panel links are optional, but if supplied they must open and focus the correct item.

An accordion may not sit directly beside tabs, a second accordion, or a dense comparison table. Adjacent interaction patterns make readers choose a mechanism before they can choose content. It may not interrupt ordered steps, split a warning from its consequence, or sit between a product price and the conditions governing that price. Do not place a promotional banner inside the group or immediately after every panel; promotion competes with the reference task and makes expansion feel like a sales trap.

Anatomy

The labelled anatomy contains seven parts:

1. Group heading: names the shared subject in the surrounding document hierarchy.
2. Item label: predicts the specific content without vague labels such as “Learn more”.
3. Disclosure control: a native summary or a button that receives keyboard focus and toggles one panel.
4. State indicator: communicates open or closed visually while the programmatic state is exposed through native semantics or aria-expanded.
5. Panel: contains the answer or reference detail and remains in the initial DOM.
6. Control relationship: native <details>/<summary> semantics or aria-controls plus matching IDs associate each control with exactly one panel.
7. Item boundary: spacing, border, and DOM grouping keep one label from appearing to control a neighboring answer.

The visible chevron is decorative. Hide it from assistive technology because the expanded state already supplies the meaning. Rotation alone cannot communicate state; the control semantics must do that.

Stay Updated on AI Visibility Trends

Get the latest insights on AI mentions, brand monitoring, and optimization strategies.

Email address

Subscribe

Design examples

Every variant uses the same fields and DOM-presence rule. Choose the variant by reading task, not by decoration.

Standard single-open group

Opening one item closes the previously open item. Use this when panels are alternatives and readers normally need one at a time, such as mutually exclusive troubleshooting symptoms.

Multi-open reference group

Readers can keep several panels open. Use this when they may compare or combine supplementary details, such as supported file types and account permissions. If simultaneous comparison is the primary task, use a visible table instead.

Default-open orientation

Open the first or most common item on initial load when it demonstrates the content pattern and provides useful orientation. Never open more than one item merely to fill space.

Compact FAQ variant

Use question labels and concise standalone answers. The interaction does not itself justify structured data; schema depends on the content type and exact visible records.

Long-content stress state

A panel with more than two short paragraphs signals that the material may deserve a visible section. The stress variant exists for testing wrapping, links, lists, focus, and responsive flow, not as the normal editorial target.

Parameters

The contract separates group behavior from item content so every platform can preserve the same labels, states, and relationships.

The first parent heading maps to heading. Each nested item’s first heading maps to label, and everything after it maps to that item’s content. This is an explicit nested-item mapping, consistent with the base precedence and body rules. open=true sets initial presentation only; it does not change content importance. When linkable=true, navigating to an item fragment must expand it, move focus predictably, and leave the heading visible below any sticky header.

Syntax and code examples

All three notations represent one canonical group. They may render different wrapper classes, but they must preserve content in the initial HTML, source order, accessible names, and state.

Portable Markdown directive

:::accordion{mode=multiple linkable=true}
## Export details

::item{id="included-fields" open=true}
### Which fields are included?

The export contains the fields currently available to your account and report scope.
::

::item{id="filter-behavior"}
### Do filters affect the export?

Yes. Confirm the active date range, market, and status filters before creating the file.
::
:::

Hugo shortcode

{{< accordion heading="Export details" mode="multiple" linkable="true" >}}
{{< accordion-item id="included-fields" label="Which fields are included?" open="true" >}}
The export contains the fields currently available to your account and report scope.
{{< /accordion-item >}}
{{< accordion-item id="filter-behavior" label="Do filters affect the export?" >}}
Yes. Confirm the active date range, market, and status filters before creating the file.
{{< /accordion-item >}}
{{< /accordion >}}

This is the Hugo adapter specification. A repository does not satisfy it by adding classes to arbitrary headings; it needs a renderer that produces native disclosure HTML or an equivalent button-and-panel relationship.

WordPress block

<!-- wp:amicited/accordion {"heading":"Export details","mode":"multiple","linkable":true} -->
<!-- wp:amicited/accordion-item {"id":"included-fields","label":"Which fields are included?","open":true} -->
<p>The export contains the fields currently available to your account and report scope.</p>
<!-- /wp:amicited/accordion-item -->
<!-- wp:amicited/accordion-item {"id":"filter-behavior","label":"Do filters affect the export?"} -->
<p>Yes. Confirm the active date range, market, and status filters before creating the file.</p>
<!-- /wp:amicited/accordion-item -->
<!-- /wp:amicited/accordion -->

The registered WordPress block stores the canonical fields rather than relying on a visual group of unrelated Details blocks. Its server render must emit every answer before interaction.

Examples

Good example

Account deletion details appears after a visible explanation of what deletion does and a visible warning that it is irreversible. Its three labels are “What happens to scheduled exports?”, “How long does a requested archive remain available?”, and “Can another administrator cancel the request?” Each panel contains one optional branch, all answers are in HTML, and keyboard focus is visible.

This works because the main consequence and required action remain visible. The accordion holds secondary questions that apply to different readers, and each label lets a reader predict whether opening it is worthwhile.

Bad example

Choose your plan contains closed panels labelled “Starter”, “Team”, and “Enterprise”. Price, usage limits, contract term, cancellation conditions, and availability are inside the panels. Only one plan can be open at once.

This fails because purchase criteria need side-by-side visibility. The reader must repeatedly open panels and remember facts, while a noninteractive extractor may miss client-loaded prices. Replace it with a visible price or specification table and reserve disclosure for optional details such as invoice formats or uncommon eligibility rules.

Schema markup and accessibility

Accordion has no dedicated Schema.org type. The interaction feeds no structured data merely by existing. If its records are genuine questions and answers, the FAQ content contract may feed FAQPage; if the group contains product details, policies, or troubleshooting notes, use only the schema justified by the page and content. Visible text and any structured representation must match.

Prefer native <details> and <summary> for straightforward disclosures because the browser supplies keyboard operation and state semantics. Where design or single-open behavior requires a custom implementation, each control must be a button, expose aria-expanded="true" or "false", reference its panel with aria-controls, and have a unique ID that the panel can reference with aria-labelledby. Do not place the control on a div with a click handler.

Enter or Space must operate the focused control. Tab moves through controls and interactive content in the open panel; focus must not enter closed content. Opening or closing a panel normally leaves focus on its control. Arrow-key navigation between headers is optional, but if implemented it must not replace normal Tab behavior.

Keep all labels in the accessibility tree and all answers in source HTML. A visually closed panel may use native disclosure behavior or a supported hidden state, but its contents must become available when expanded without a second fetch. The collapsed state must not cause duplicate content through separate desktop and mobile copies. Test at 200% zoom, with long labels, keyboard only, reduced motion, and a screen reader. Animate height or icon rotation only when the motion can be suppressed and content is not delayed.

Writing rules

The label carries the cost of the interaction, so it must make a precise promise. Write 3–14 words and usually no more than 120 characters. Use a direct question for FAQ content and a descriptive noun phrase for reference content. Avoid “More”, “Details”, “Read this”, and labels that differ only by a number.

Use 3–8 items per group. Each panel should normally contain 20–120 words and no more than 250. Two short panels are clearer as open prose; nine or more need grouping, visible navigation, or editorial consolidation. Keep labels grammatically parallel and arrange items by reader task, expected frequency, or a real sequence of categories—not alphabetically unless lookup is genuinely alphabetical.

Panel tone is direct, self-contained, and factual. State the answer in the first sentence because a reader has already paid an interaction cost. Define any necessary term within the panel or in visible text immediately before the group. Do not start with throat-clearing such as “There are several things to consider.”

Never put these only inside an accordion:

• the page’s direct answer or unique value proposition;
• safety warnings, contraindications, legal obligations, or irreversible consequences;
• price, availability, material product limits, or required purchase conditions;
• ordered steps, prerequisites, or a completion check;
• evidence necessary to support the surrounding claim;
• a primary comparison or decision matrix;
• forms, checkout controls, consent, or the page’s main call to action;
• another accordion, tabs, or a carousel.

A compact list, small table, inline link, or supporting image is acceptable when it belongs entirely to one optional item and remains usable on mobile. If a panel needs its own table of contents or more than one heading level, promote it to a visible section or separate page.

Post types that use it

The postTypes frontmatter array is the source of this usage matrix. Inclusion means the element is available under the stated condition, not mandatory on every page of that type.

QA checklist

• A visible direct answer appears before the accordion.
• Every item is optional reference content, not information all readers need.
• The group has 3–8 items with precise, parallel labels.
• Every panel’s complete text is present in the initial server-rendered HTML.
• No answer depends on a click-triggered network request or client-only insertion.
• Native details/summary or real buttons provide correct keyboard behavior.
• Custom controls expose aria-expanded, aria-controls, unique IDs, and an associated panel label.
• Focus is visible, remains predictable after toggling, and cannot enter a closed panel.
• Long labels wrap without clipping, overlap, or hiding the state indicator.
• The layout works at 200% zoom and on a narrow viewport without horizontal scrolling.
• Motion respects reduced-motion preferences and never delays access to content.
• Individual fragment links, when supported, open and reveal the correct panel.
• Structured data is based on content meaning, not the accordion’s appearance.
• FAQPage records, if emitted, exactly match the visible question and answer text.
• No nested accordion, adjacent tab set, repeated mobile copy, or main CTA is present.
• The page still communicates its primary answer when every panel is closed.

Frequently asked questions

The frontmatter stores the canonical FAQ records for this page. Their answers reinforce the implementation boundary: content may be visually collapsed, but it remains present, accessible, and secondary to the visible answer.