Open UI
View Research

Exclusive Accordion (Explainer)

Table of Contents

Background

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:

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):

User Needs

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.

Proposal

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

Name

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 name, group, or exclusive.

Proposed solution: Use name, since it’s consistent with existing features.

Interaction with open attribute

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 innerHTML.)

Proposed solution: Enforce exclusivity only for user interactions, use of the open IDL attribute, or setting the open attribute via setAttribute (or setAttributeNS, setAttributeNode, or 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.

Printing

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).

It’s also possible that developers could do this in JavaScript, specifically for printing, but then it certainly wouldn’t be a default and probably wouldn’t be done often.

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 name and open attributes during the beforeprint and afterprint events.

Existing issues with details

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.)

Further reading:

Accordions with exactly one item open

Some accordions (such as the one on the Pixel product page above) always have exactly one item open, and do not allow zero items to be open. (This could be called an exact-exclusive accordion.) This is a somewhat more complicated widget, because the open/close control disappears from the item that is open or becomes disabled. It’s not clear how such widgets could be modeled with this design, other than by ensuring that developer Javascript to handle this.

Proposed solution: For now, do not attempt to address this pattern directly, but make sure it’s possible to do in Javascript.

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 (details elements).

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).

Scope

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.

Alternatives considered

CSS Toggles

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.

It’s likely worth exploring this alternative further, particularly to understand what integration with CSS and JavaScript it would have, and how that integration would affect its use.

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.