Repository navigation
Bug - Expandable section - Update docs to highlight expandable sections as headings #8506
Description
Describe the problem
Whenever the text of the button for an expandable section introduces/summarizes the content it describes, the toggle is also functioning as a heading. In such cases, the user should use the detached variant of the expandable section and wrap the toggle button in a heading element.
This use case should be called out in the examples/documentation.
Expected behavior
The correct way to implement this is to surround the button with the heading tag. For example:
<h3>
<button type="button" aria-expanded="true" class="accordion-trigger" aria-controls="sect1" id="accordion1id">
See more important stuff
<span class="accordion-icon"></span>
</button>
</h3>
<div id="sect1" role="region" aria-labelledby="accordion1id" class="accordion-panel">
This is the important stuff that is hidden/shown by the button above
</div>
The toggleText, 'toggleTextCollapsed, and toggleTextExpanded are typed as strings, but you can use the toggleContent to send a heading
For example:
<ExpandableSection
toggleContent={
<h2>I am a heading</h2>
}
onToggle={onToggle}
isExpanded={isExpanded}
>
This content is visible only when the component is expanded.
</ExpandableSection>
The problem is that the heading tag, in this case, an h2, is a child of the button. This will lead many assistive technologies to tread the heading as presentational so they aren't picked up by the heading list. See: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role#all_descendants_are_presentational
The OCM code base uses numerous expandable sections and new work will be adding additional expanding sections in the near future.
Any other information?
I'm an expert in mediating accessibility issues. Please feel free to contact me via the Internal Red Hat slack if you have questions or need assistance.
Metadata
Metadata
Assignees
Type
Projects
- Status
Activity
nicolethoen commentedon Jan 13, 2023
@kdoberst I believe that this can be accomplished using the detached variation of the expandable section - https://www.patternfly.org/v4/components/expandable-section#detached
I'd be happy to create a codesandbox example for you if needed.
kdoberst commentedon Jan 16, 2023
Yep I think that would work. Might be nice to push that as the solution since it is the more accessible solution.
nicolethoen commentedon Jan 17, 2023
I will update this issue so that it encompasses updating the docs to include the accessibility information and highlighting the way that solution accounts for those particular a11y concerns.
[-]Bug - Expandable section - Cannot wrap button in a heading tag - accessibility[/-][+]Bug - Expandable section - Update docs to highlight expandable sections as headings[/+]github-actions commentedon Dec 27, 2024
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.
github-actions commentedon Apr 9, 2025
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.
github-actions commentedon Jun 10, 2025
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.
thatblindgeye commentedon Sep 26, 2025
In addition to the above, it may be nice to allow the ability to provide a heading wrapper without needing to use a detached variant - we could add a prop to customize the wrapper element (the one with class
styles.expandableSection}__toggle) to either be a div by default, or one of the 6 heading levels.