Skip to content

docs: add Accessibility section to Accordion page #5902

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
web-padawan merged 3 commits into from
Aug 28, 2026
Merged

docs: add Accessibility section to Accordion page #5902

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
34c22a8
docs: add Accessibility section to Accordion page
web-padawan Aug 28, 2026
66c5ecc
docs: simplify Accordion heading level wording
web-padawan Aug 28, 2026
53af335
Merge branch 'main' into docs/accordion-heading-level
web-padawan Aug 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions articles/components/accordion/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,39 @@
endif::[]
--

== Accessibility

Each panel's summary is rendered as a heading -- an element with `role="heading"` that wraps a button -- and the panel's content as a region labeled by that heading, as recommended by the WAI-ARIA accordion pattern. Screen readers can therefore list the summaries as headings and announce whether each panel is expanded or collapsed.

Check warning on line 144 in articles/components/accordion/index.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Abbr] 'WAI' has no definition.

Raw Output:
{"message":"[Vaadin.Abbr] 'WAI' has no definition.","location":{"path":"articles/components/accordion/index.adoc","range":{"start":{"line":144,"column":189},"end":{"line":144,"column":192}}},"severity":"WARNING","code":{"value":"Vaadin.Abbr"}}

By default, the headings have no level, so screen readers announce them at their default level. The `aria-level` attribute can be [since:com.vaadin:vaadin@V25.3]#customized# to match the surrounding page structure -- for example, level 3 inside a section with an `<h2>` title:

[.example]
--
ifdef::flow[]
[source,java]
----
accordion.setHeadingLevel(3);
----
endif::[]

ifdef::lit[]
[source,html]
----
<vaadin-accordion heading-level="3">
----
endif::[]

ifdef::react[]
[source,tsx]
----
<Accordion headingLevel={3}>
----
endif::[]
--

The same level is applied to all panel headings.


== Best Practices

Accordions are suitable when users need to focus on smaller pieces of content at any given time. However, when all of the content is relevant to the user to make a decision, Accordions should be avoided. Content areas that are logically linked should be grouped together in one panel.
Expand Down
Loading