Exclusive Accordion (Explainer)
- Last updated: September 11, 2023
- Feedback: https://github.com/openui/open-ui/issues/725
- HTML specification pull request: https://github.com/whatwg/html/pull/9400
Table of Contents
- Developer Demand for Exclusive Accordion
- User Needs
- Alternatives considered
A disclosure widget (research) is a UI that shows a summary or heading along with an indicator (sometimes a triangle or a plus sign) that allows the widget to be expanded to show additional details. An accordion (research) is a sequence of related disclosure widgets. Some accordions are exclusive accordions, which means that at most one of the disclosures in that accordion can be open at the same time.
The existing HTML
details element represents a disclosure widget. A sequence of
details elements can be used for a non-exclusive accordion. However, there is not a current web platform feature for exclusive accordions.
It is worth noting that the HTML
details element is not currently as styleable as it needs to be to meet many use cases. Improving styleability of
details will be addressed in a separate proposal, intended to address both better ability to style/replace the disclosure triangle, and to fit the parts of a
details into different types of layout (such as grid). For example, there is no standardized or interoperable way to replace the disclosure triangle’s image or to change its placement relative to the summary or the rest of the content of the details.
Developer Demand for Exclusive Accordion
Design systems that offer accordion widgets vary as to whether those widgets are exclusive or not. Based on the systems documented in the accordion research, it seems more common for them not to be exclusive, however, some systems offer an option for being exclusive, and some systems offer only exclusive accordions.
Some examples of exclusive accordions on live sites:
- Parsons Table product page at Room and Board (Style/Size/Top/Base accordion on right side of page)
- Aaron Dining Chair product page at Pottery Barn (Overview / Responsibly Made / Dimensions & Care / Shipping & Returns accordion on right side of page)
- Saatva Classic Mattress product page (a few pages down, with the first heading “Plush & breathable sleep surface”)
- The “Property Details” section of a Marriott Hotels hotel page
Some examples of exclusive accordions where exactly one item is always open (discussed below as an exact-exclusive accordion, which requires some additional code in addition to the proposed markup):
- Pixel 7 product page on the Google Store (one accordion in each of the sections on Performance, Photography and Video, Protection, and Pixel Portfolio)
- Zachary’s Chicago Pizza FAQ
Developers regularly use exclusive accordions on the Web. Today, that generally means that they build their own widget rather than using a widget provided by the platform, because there is no such widget.
This proposal is suggesting that we add features for exclusive accordions to the platform. Doing so would help users because it would make (or at least would enable making) the user experience more consistent, and generally better, in a number of areas:
- keyboard shortcuts and focus handling,
- exposure via ARIA to assistive technology, and
- integration with browser features such as find-in-page.
Reducing the need for developers to build their own widgets should also reduce the size of pages that use such widgets, which reduces the time and bandwidth needed for users to load those pages.
I propose to add an attribute to the
details element. All
details elements in the same tree that have the same value for this attribute would form an exclusive accordion. The syntax of this attribute and the rules for matching its values would match the
name attribute and its use in defining radio button groups.
When these attributes are used to form a group, it means that any user action or API that causes one of the
details elements in the group to open causes all other elements in the group to close.
Open design questions
There are many options for naming this attribute, and they differ as to how well they:
- are concise,
- indicate that something happens when multiple elements use the same value, and
- indicate that the attribute causes the grouped elements to become exclusive (so that only one can be open).
Choices for its name also differ as to whether they’re already used for other things in HTML. (This could be either an advantage or a disadvantage.) In particular,
name is used for grouping related form controls.
Some possibilities for the attribute’s name are
Proposed solution: Use
name, since it’s consistent with existing features.
Should this grouping cause the insertion of a
details element with the
open attribute already set to have the
open attribute removed if it would violate the grouping constraint? If so, is such attribute removal on insertion acceptable (both for its complexity and for conformance with architectural principles)? If not, is it ok that we allow developers a loophole to violate the exclusivity semantics?
(This applies both to insertion by the parser and insertion through other methods like setting
Proposed solution: Enforce exclusivity only for user interactions, use of the
open IDL attribute, or setting the
open attribute via
setAttributeNodeNS). Do not enforce exclusivity when the
open attribute is set by the parser, when it is set as a result of cloning a node, or when an element is moved to a new document. Do not enforce exclusivity for elements whose root is not a Document or a ShadowRoot.
For many accordions, it is desirable for the print layout of the page to have all items opened. This is currently not possible to do from a style sheet, but it probably should be possible, and it’s possible that it should be the default. The presence of exclusive accordion semantics make this more difficult, because of the rule that only one item can be open. (However, some of the time it will make more sense to print what is on the screen rather than printing all of the content. It’s also not clear to me how often distinguishing between these cases should be a developer decision or should be based on a user decision.)
In theory this could be addressed with a model where details elements were implemented on top of developer-exposed CSS Toggles, and developers could disable the effects of those CSS Toggles when printing. Or, more generally, this could be addressed with a solution that treats things like accordions and tabs as possible interactive presentations of markup that is semantically headings and sections, and allows the use of CSS (or some other mechanism tied to media queries) to choose between them. However, this would be a relatively major change, worthy of its own explainer. It also has many of the same problems as CSS Toggles (see below).
We should find and consider alternative approaches for addressing this issue.
Proposed solution: For now, do nothing here. If developers want all of the
details elements on a page to print open, they need to change both
open attributes during the
Existing issues with
There are some existing issues with
details elements that may need to be resolved before
details elements can be used in a way that fulfills the goals of this proposal.
First, there are issues related to interactive content in the
summary element causing various keyboard and accessibility issues. See https://github.com/whatwg/html/issues/2272 (and its links, which include browser bugs) for details. There are also some related questions about selection in
summary as discussed in https://github.com/whatwg/html/issues/3191 and https://github.com/whatwg/html/issues/8707 .
Second, there are some questions about the relationship between headings and
summary elements. See https://github.com/whatwg/html/issues/8864 . (This is not surprising since the accordion pattern is one possible interactive presentation of markup that is semantically pairs of headings and sections.)
Accordions with exactly one item open
Possibly-resolved design questions
Changes to ARIA roles or keyboard behavior
It’s possible that the presence of a group should change the ARIA roles for the
details or its
summary or change their default keyboard behavior.
If this is the case, it seems likely that such changes may also be desirable for non-exclusive accordions (see next question).
Based on the discussion on 2023 April 27, it seems like at least default keyboard behavior for accordions is undesirable because it leads to bad user experience particularly for users on small or highly-zoomed displays (where the content of a single item is less likely to fit within the display).
Use case for non-exclusive accordion semantic?
This design assumes that there isn’t a use case for the semantic of a non-exclusive accordion, since a non-exclusive accordion is largely indistinguishable from a sequence of disclosures (
However, it’s possible there may be value in establishing such a semantic connection between the
details elements in a non-exclusive accordion. (See previous question for one possible reason.)
If such connection is valuable, then that would favor a design that separates the ideas of connecting the
details elements into a group and making the group exclusive.
In the discussion on 2023 April 27, no use cases for a platform feature for connecting a non-exclusive accordion were raised (assuming the conclusion to the keyboard behavior issue above stays as-is).
Should the name be scoped to something smaller than the document (for example, only to siblings) or to something larger than the document (such as the flat tree)?
I think scoping only to siblings would be problematic because there are valid use cases for putting each
details element into some sort of sectioning markup, and that scoping on the flat tree would be problematic because having names cross shadow root boundaries would break encapsulation.
The CSS Toggles proposal is a much more complex proposal that would be able to describe exclusive accordions and many other things. However, it has a number of issues related to developer experience, accessibility, and other things, and it’s not clear whether the proposal is viable.
Toggle (expand/collapse) button or attribute
The proposal for a toggle (expand/collapse) feature probably falls somewhere between this proposal and CSS Toggles in terms of how general it is. It may be a reasonable alternative to this proposal, or it may be reasonable to do both.
I think it’s possible that there’s a risk that this proposal becomes a more general feature than currently intended, which would have both some of the advantages and some of the problems that CSS Toggles have.
Panelset (aka “Spicy-Sections”)
Within Open-UI there was another proposal which was to be called panelset. Earlier it was called “spicy sections” in order to avoid bikeshedding or misconceptions that it was yet ready to be thought of as a proposal. The distinguishing characteristic of that proposal is that introduced the idea that certain ‘widgets’ had more in common with scrollbars than they do inputs. That is, they are often reasonable choices of design particular to the media or situation. Panelsets proposed the introduction of other affordances to handle (in document, see also 559) tabs and accordions. Thus, it is less general than CSS Toggles, but more general than all the others mentioned here.)
The panelset proposal has enough open questions that it’s a bit hard to assess.
At the same time, this proposal and panelset address problem spaces that, while intersecting, are different enough that it would still be reasonable to do both if we conclude that both are good.