diff --git a/articles/components/accordion/index.adoc b/articles/components/accordion/index.adoc index 04f66c86ec..73d2da141b 100644 --- a/articles/components/accordion/index.adoc +++ b/articles/components/accordion/index.adoc @@ -139,6 +139,39 @@ include::{root}/frontend/demo/component/accordion/react/accordion-disabled-panel 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. + +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 `

` title: + +[.example] +-- +ifdef::flow[] +[source,java] +---- +accordion.setHeadingLevel(3); +---- +endif::[] + +ifdef::lit[] +[source,html] +---- + +---- +endif::[] + +ifdef::react[] +[source,tsx] +---- + +---- +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.