New block: Accordion block

[mapk]

There's been a few requests for an Accordion block in core. Let's start exploring how this looks.

Requirements

• Pure CSS.
• Add accordion headers with arrow icons.
• Allow any block to be added within an accordion section.

Is the accordion section simply a Group block that is able to be collapsed? Basically it would work similarly to the Settings sidebar sections.

Kudos to @melchoyce for this idea. Some examples she shared recently:

https://codepen.io/raubaca/pen/PZzpVe
https://codepen.io/vinsongrant/pen/qbGKed
https://codepen.io/abergin/pen/ihlDf

[paaljoachim]

Great! Yeah this is needed. I have seen a few requests over a longer period of time asking for an accordion block.

[carolinan]

If there is a fallback for IE, it could be a details element, reducing the markup drastically.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details

[aristath]

Actually accordions don't need CSS, JS etc... We could simply use a <details> HTML element.

<details>
  <summary>This is the accordion title</summary>
  This is the accordion content
</details>

^ The above code would render like this:

This is the accordion title

This is the accordion content

Coincidentally I started building a details block yesterday and it works fine that way.

We can add options to change the styling of the triangle etc if needed, and there's some extra info on this article

Note: accordions built this way are 100% accessible and they just work because native-HTML 😄

---

Edit: It looks like I was writing this comment at the same time as @carolinan above 😆

[mtias]

We could do a render fallback on the server for IE, or also consider not doing anything (it'll still render the content, just expanded by default).

[aristath]

having it expanded by default in IE is not a big issue... As long as it renders and looks OK I don't think we should add any extra scripts etc to make IE behave like modern browsers. Supporting IE is not the same as making it look & behave identically 👍

[paaljoachim]

Here are some plugin examples that use accordion blocks.
Twenty Twenty.
Gutenberg plugin activated.

Atomic Blocks
https://wordpress.org/plugins/atomic-blocks/

Backend:

Title selected:

Content selected:

Frontend:

---

Co Blocks
https://wordpress.org/plugins/coblocks/

Backend.

Title is selected.

Content is selected:

To add a new accordion one clicks the Inserter area similar to the Group Block.

Frontend:

---

Accordion Blocks by Phil Buchanan
https://wordpress.org/plugins/accordion-blocks/

Backend.

Title selected.

Content selected.

Frontend.
There is a minus on the right side when the accordion is open. When the accordion is closed there is a + sign.

[ZebulanStanphill]

It's worth noting that using heading elements in the <summary> is valid, and that would be the correct way to handle a lot of use-cases for accordions like step-by-step how-to articles.

Should the Accordion block have an option to switch the contents of the <summary> from plain (no inner elements other than text) to different heading levels (similar to the options provided in the Heading block); or should the <summary> be an entire InnerBlocks area where you can insert whatever typography-related block you want?

I'm currently leaning towards the former solution, since it's less complicated, and it's much easier to migrate from that to the latter solution in the future than to go the other way around.

[LukaszJaro]

The only thing with IE11 and <details> HTML element is they are expanded by default as mentioned. The problem with that is it defeats the purpose of toggles.

[aristath]

The only thing with IE11 and <details> HTML element is they are expanded by default as mentioned. The problem with that is it defeats the purpose of toggles.

IE11 doesn't break with a <details> element... and sure, it's not the same as it is in a modern browser but that's not a dealbreaker.
Nobody on IE expects to see the same thing they'd see when using Firefox/Chrome/Brave/Whatever. Different browsers exists for different people, different tastes and needs or limitations. If they use IE, then the rest of the planet shouldn't suffer for it.
A workaround could be implemented for IE by loading a conditional script that would tweak the behaviour, but... is it really worth it? Adding extra html & JS in other browsers just to make IE work would do a lot more damage overall, and we can't really move forward if we keep looking at a broken thing from 7 years ago.
They can still see the content, they can read everything, things are properly styled, just not collapsed by default.

[LukaszJaro]

I understand what your saying @aristath I just have a very strange requirements with a project right now which only supports IE11 ! yea...it is an internal site like a intranet type. The content editor wanted some toggles..

And there is still years of support for IE11 :(

https://death-to-ie11.com/

[enriquesanchez]

This issue and related PR were discussed today by the Accessibility team.

The team suggests to not use the <details> element for this scenario, and instead follow the ARIA Authoring Practices implementation for an accordion component

For more details on why <details> is not a suitable element, please see:

1. https://daverupert.com/2019/12/why-details-is-not-an-accordion/
2. https://adrianroselli.com/2019/04/details-summary-are-not-insert-control-here.html

As always, please feel free to ping the team in the #accessibility Make WordPress Slack channel if there are further questions or comments.

[mapk]

Here's an iteration on the Accordion block.

[ZebulanStanphill]

That looks pretty good. One thing we'll need to make sure to include in the block's toolbar is a way to switch the HTML element of the heading, including h1-h6 options, plus maybe even p? We should be able to extract the heading level control from the Heading block and reuse it here.

[mapk]

Here's a prototype of how I imagine this block working.

• It uses similar block interactions as the Group and Heading blocks.
  • The Accordion heading allows a heading level change.
  • The large + Inserter button below works like the Group block.
• The heading is editable on focus of the Accordion block.
• Adding content to the collapsable region requires clicking the + Inserter to add a block.
• When resting, the Accordion block collapses to hide the content region.
• When focused, the Accordion block open to show the content.

[mapk]

Some recent design feedback lead me to add a couple Style Variations.

Default

Style Variation 1

Style Variation 2

[mapk]

Further design feedback from @melchoyce suggested that we just drop a Paragraph block into the content area rather than a big + button. The flow would look something like this.

[mapk]

Recent design feedback:

Arrows

The arrows need to be oriented differently. Rather than up/down, they should be right/down.

Style variations

There's some question as to whether or not the variations above make sense to include as style variations. I'm waffling back and forth on this one. They are "style" variations that only manipulate styling... so that makes sense to me.

Default variation

Should the above Style Variation 2 actually be the default because there's basically no styling? It might make it easier to themes to apply their own styles with that as the default.

[ZebulanStanphill]

Yeah, I'd favor a default style that's easy for themes to override.

[paaljoachim]

Here is a draft PR for the Details Block:
#23940
There is some crossover of the Accordion and the Details Blocks.

[joedolson]

The details block is really not a substitute for an accordion, and should not be used in that manner. It's expected to show and hide only one panel, and doesn't operate as a group. I think we should still add an accordion block.

[amberhinds]

I was just going to write the same thing RE the details block. Here's a good example of how the accordion block should be coded for accessibility.

[webd-uk]

The details block is really not a substitute for an accordion, and should not be used in that manner. It's expected to show and hide only one panel, and doesn't operate as a group. I think we should still add an accordion block.

I'd like to highlight that the new Twenty Twenty-Four theme uses multiple Details Blocks to provide the functionality of an accordion on the "FAQ" panel of the home page.

The only thing missing from the Details Blocks is a setting "Close other Details Blocks when opened" which would negate the requirement for an Accordion Block.

So ... if the Details Block shouldn't be used to create an accordion then really the new theme shouldn't be promoting it as such surely?

[LukaszJaro]

@webd-uk I would a ticket for that.

@alexstine would this be considered accessibility issue with the way the 2024 theme is using the details block as accordion in FAQ section? Also what uses cases should the details element be used?

[webd-uk]

@LukaszJaro I did with #55483 ... shall I re-open it? Or do you mean raise a ticket about the Twenty Twenty-Four theme use of the Details Block? Because if you do I'd rather not as having played with the Details Block I think it's perfect for an accordion if it can just have the option added to auto-close other Detail Blocks.

[joedolson]

The 2024 theme is using a series of details blocks in a group, but I don't see any way that they're describing it as an accordion. The fact that a group of details are used in sequence does not make it an accordion, and I don't see anything that promotes it as an accordion. If you can point to some specific text in which the FAQ pattern is described as or promoted as an accordion, I'm happy to push back on that, but while I wouldn't use this pattern, because it has woefully insufficient semantics for what it represents, it's not described as an accordion, as far as I can tell.

[joedolson]

@webd-uk Re: "The only thing missing from the Details Blocks is a setting "Close other Details Blocks when opened" which would negate the requirement for an Accordion Block."

This is not true. The thing that's missing from the details block is heading semantics. An accordion should have headings that indicate each item within the accordion. Inside those headings, there should be buttons that trigger the accordion behavior.

The details block has a summary element, which has the role of button natively. The button role overrides all internal semantics, so no matter what content is inside the summary element, there are no headings present. That is the crucial reason that details is not a substitute for an accordion. As soon as you have enough content that headings are an important element for navigating content, details ceases to be sufficient.

[webd-uk]

@joedolson Ah, OK. So adding a "Close other Details Blocks when opened" setting to the Details block would not make it behave like an accordion because without the heading semantics it cannot be an accordion. As such, do you think that #55483 is valid and should I should re-open it?

[joedolson]

No, I think that #55483 is not a valid request. There shouldn't be any relationship between different details elements on a given page; they should each be treated as an independent element. A change like that would just increase the impression that the details block is equivalent to an accordion.

[webd-uk]

OK ... in that case I'll be looking forward to the forthcoming Accordion Block!

Thank you.

[ocean90]

The details element can now have a name attribute to make it an "exclusive accordion".

[joedolson]

That makes the behavior more like an accordion, but it's still significantly lacking in semantics. It would function in an accordion style, but it would be a very poor accordion. In principle, I'd support adding the attribute on the grounds that WordPress should support all standardized HTML. However, I would still stand on the opinion that it is not an accordion, and we should provide an accordion that does meet accessibility standards.

[westonruter]

@joedolson What are the lacking semantics? Are they lacking in the spec or not implemented in browsers or what?

[amberhinds]

@westonruter take a look at this example of how the accordion block should be coded for accessibility that I shared in September.

[joedolson]

The most specific gap is that an accordion should be a list of heading elements that contains buttons to expand and collapse the content.

The semantics of the details/summary elements, however, are designed so that you can only place a heading inside the summary element; you can't wrap the summary in a heading without breaking the control. This reverses the semantic relationship, and removes the heading semantics.

A heading with a contained button is a heading that has text equivalent to the button text plus a button that has the interactivity.

A summary elements with a contained heading, however, is an interactive element that does not contain any heading semantics.

As an isolated element, a single summary/details combination is a great, easy to implement disclosure widget. But as a group of related elements, it's lacking key navigation and structure elements.

I don't off-hand know whether this should be primarily blamed on browser vendors or on AT vendors. The spec doesn't provide clear guidance about how headings should be handled within a summary element, and as of the last testing publically available, JAWS offered no support for headings within summary on any browser, which eliminates a very large percentage of users.

That test dates to May 2022, though, so it may be due a revisit.

[LukaszJaro]

@c4rl0sbr4v0 how did the experiment go with the interactivity api?

I will be happy to try an experiment of an Accordion approach with the Interactivity API. I will keep you posted in this issue.

[cbravobernal]

I am now working on making the Interactivity API public in WordPress 6.5.

Until then, I won't have enough time 😅 . But after that, it would be a great example for this new feature!

[Nyiriland]

🖐️ Gey gang! I work in an agency and we use accordions quite a bit on our projects. It would be amazing if we could use something from core instead of resorting to a plugin, or building out custom blocks (pretty sure we've done both in the past). Accordions are a very common layout feature on modern sites, for things like feature lists, or FAQs.

The reason Details doesn't fulfill the same purpose for me is two-fold:

• It looks like a bullet point (and I thought it was until someone pointed out it wasn't)
• A user would need CSS knowledge to be able to update it to a more "modern" styled accordion; right now it feels pretty dated as-is (and I'm pretty sure it's just using the default html styles).

[jarekmorawski]

Love the discussion so far! While working on some patterns for WooCommerce, I found the Details block limiting and would love to update it with more features or build a dedicated accordion block. I put together a design proposal that solves most of the issues I ran into and most of what @Nyiriland described earlier).

Firstly, the block would consist of two parts: a trigger and a hidden content area. Both could be anything: from buttons to images to text to tables. Clicking on the trigger block would open the accordion.

For instance, we'd let users add a button that will open the accordion.

Going further, if we update the button to support icons and offer some extra layout flexibility (like "Stretch" as a justification setting that will spread the button's inner blocks even across its width), we'd make it easy to build modern-looking accordions with chevrons, -/+ buttons, text labels, etc.

As for the content area, it could contain any number of blocks. Here's how the block structure would look if we were to build an accordion for a price filter block in a product catalog page template in Woo.

We'd use block states (related to #57719, #38277) to let users customize the appearance of a collapsed and expanded accordion. This would enable designers and builders to use different text labels or icons for each block state, e.g., - when the accordion is open, and + when it's closed.

We'd also let users decide if the accordion is open by default and whether other accordion blocks on the page should collapse automatically when this one's open (this is a pretty common behavior on the web).

I'm a bit torn about this part because it can cause issues when enabled on multiple blocks, but then building an accordion group parent block just for this setting would add unnecessary complexity.

We would let users specify the block's width, justification, and orientation to enable more creative, non-standard layouts. For instance, they'd design an accordion where the trigger is on the left or right, which is a common sight in e-commerce.