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

---

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

[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 :+1:

[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: https://github.com/WordPress/gutenberg/pull/23940 There is some crossover of the Accordion and the Details Blocks.

[kellychoffman]

Looking good. Liking the iterations so far and how this is evolving. Some feedback:

• Add the interaction/flow for adding an additional accordion section
• Add the interaction/flow for adding an additional block within the accordion content
• Add block settings for accordion

To summarize above: I think it would be good to see the full block adding flow in context with the sidebar and its settings

• I would also push the styles a bit more. Right now they are very subtle and I wouldn't consider them a different style, more just removing/adding background+border colors. Try playing more with layout, spacing, position of elements. Similar to this approach: https://github.com/WordPress/gutenberg/issues/22071#issuecomment-624637501

[pablohoneyhoney]

+1 to @kellychoffman notes. It's relevant to find the right customisation while adjusting to any theme. The icon seems a bit too abstract, worth exploring some options there.

Note that this https://github.com/WordPress/gutenberg/pull/23971 seems to be happening which affects slightly your mock ups.

[ZebulanStanphill]

@pablohoneyhoney Not sure if you're referring to the block icon or the expand/collapse icon, but in the case of the latter, I think it's definitely worth trying to find a new icon to indicate expand/collapse. Right now we're using the same icons that we use for the block movers, which is confusing as the two are completely unrelated.

[pablohoneyhoney]

Now that you are saying it, both actually @ZebulanStanphill

I was referring to the block icon. Regarding the collapsable UI (arrow), unsure if there are many other patterns besides arrow or +/-.

[mapk]

I've iterated on the UX flow for this block a bit more to help explain how a new block would be added, and how to add another Accordion block below. I see each block being its own accordion to keep things simple. Wrapping multiple accordions into a wrapper can get complex in a number of ways, and I'd like to avoid that.

Taking in the recent feedback, I chose the less stylized variation as the base for this block. This does two things:

1. Makes the default state easier for themes to style.
2. Gives me a more difficult beginning to really tune the UX flow.

UX flow for adding multiple blocks and then adding another Accordion block

The Accordion block in this flow works much like adding multiple blocks in a Column. While the Columns block surfaces a large + button, the Accordion block does not, but rather presents the typical Paragraph block's placeholder. So while editing one block, hitting Enter will insert a new block below – just like in the Editor.

When clicking the parent (Accordion) block, it shows the selected border that contains both blocks. Very much like how both the Group block and Columns block work.

Deselecting the Accordion block causes it to collapse. In the gif, this is what happens when I have the Accordion block selected, but then hit the Enter key. This action adds a new cursor below the Accordion block causing it to collapse. I then type /accordion to insert a new Accordion block again.

---

Next steps

1. Work on sidebar settings to see which features the Accordion block would be good to have.
   • ie. Color for heading backgrounds
   • Toggle to keep accordion open
2. Iterate on a few simple style variations that could include borders, different arrow icons, etc.
3. Iterate on a new block icon.

Both of these will keep the block simple enough to allow themes to easily style it, but also provide necessary block settings that improve customizations. We should keep in mind that customizations with the use of "Design Tools" are different than Style variations that just provide quick and simple variations for a user to then customize further.

[jasmussen]

I left some comments related to an accordion block on this PR around a "Details" block. The gist is I could see a place for both coexisting, mostly because the details block is so minimal while still being useful.

[enriquesanchez]

I could see a place for both coexisting

@jasmussen From a user perspective, whare are the differences in functionality that these two blocks will provide?

[mariohamann]

It's great that considerations exist to bring accordions into the Gutenberg-Core! For a project I also created an accordion block.The thing doesn't run perfectly and smoothly yet, but it does its job. :)

I have made the following experiences and would like to pass them on:

Advantages of two blocks (accordion and accordion_element)

I decided early on to work with nested blocks, namely with a parent block (=accordion) and a child block (=accordion_element). The advantages are obvious:

1. the option can be offered to have other accordion elements in the frontend close when a single one opens
2. it is also possible to set the heading level for all elements at the same time, which makes accordions much more maintainable. (Use Case: Someone adds a heading above the accordion, whereupon the heading levels of each accordion element must be reduced by one).
3. from my perspective, accordions are often considered as a whole element, e.g. for FAQs or the like It would therefore also be very useful if they existed as an entire block, e.g. when moving elements. The accordion should always be moveable as a whole without workarounds and no other elements should be able to slide between the accordion elements. Concrete example: It seems strange to me if a picture under an accordion would end up inside the accordion by moving it with the arrows at once.
4. further accordion_elements can be added so quickly. In our design, we have adjusted the background of the add_button to the color of the button, so that the full width is filled in, giving a stronger resemblance to the accordion_element.

Icon on the left side?

I don't know how useful it is to position the unfolding icon on the left side by default. For example, if someone wants to include icons for orientation in their title, this will be difficult. In another project I worked with complementary icons to better structure the content.

Moving content in editor

During my development I had to learn that the content area of an accordion_element can be very painful to edit. In your design @mapk it looks like the accordion_element in the editor is unfolded when it is selected. This was also the case in my projects at first. It is a common use case that content is written first, but only then is it decided to put it into an accordion. This makes it necessary to access the InnerBlock area of an accordion_element without the accordion_element being currently selected. I don't think my solution is ideal, but it was the most feasible one: Everything is always unfolded. This way, contents of accordion_element can be moved to another accordion_element.

Separation of the title from the content in frontend and backend

Practical experience has shown that it is very useful to clearly distinguish the clickable head area from the rest when activated. This is especially important if, for example, bold print or even headings are used within the content area. The latter would also be absolutely legitimate from a hierarchical perspective, but can lead to parts of the content being larger than the accordion title. To achieve this, it was essential that an accordion_element be linked by a common frame, but at the same time the title and content had to be separated. @mapk: I therefore consider your older designs with the minimal border to be a much better default state and should still be minimal enough to make them customizable by themes. From a usability perspective, it will also only then become clear that the complete title section is clickable - which will hopefully be the case? :)

Appendix

A few more short thoughts I want to share:

• Concerning the icon, I decided on a plus ("Here you can see more"), which turns to an X ("Here you can close") after opening.
• Hover and focus styles are very important here to make it clear to frontend users that interaction is possible here. We have worked with backgrounds, even though this is not quite ideal from an A11y perspective.

I am looking forward to seeing more designs and can't wait to see the result in the core! Thanks for your efforts!

[mapk]

I've iterated on some block settings that will benefit the Accordion block.

• Style variations (minimal or borders)
• Open by default
• Animate opening and closing
• Heading color settings (text and background)

With these settings, and the settings inherent in each block (ie. Heading levels, Paragraph settings, etc.) I think users can customize these fairly well to their liking.

Notes

• As noted earlier, I've updated the Accordion arrow.

---

Next steps

1. ~Work on sidebar settings to see which features the Accordion block would be good to have.~
   • ~ie. Color for heading backgrounds~
   • ~Toggle to keep accordion open~
2. ~Iterate on a few simple style variations that could include borders, different arrow icons, etc.~
3. Iterate on a new block icon.

[mariohamann]

This is great! I like the idea to use color variations for the header! (Seeing this, I would like to be able to define "global settings" on block level so that I don't have to edit all blocks of the same type after a color change. Sort of like global blocks, only at the settings level instead of the content level, i.e. changes to the settings in one block are automatically transferred to others with the same "Global Settings". I will open a new issue. :))

Personally, I still tend to place the arrow on the right side. A quick look in Dribbble and Google Images confirmed my feeling that about 80% place the accordion icon on the right side. At the same time I understand that in this case in "minimal"-style the reference to the text would be a bit too small and the feeling of an accordion could be overlooked. What do you think about the position, @mapk? Maybe it would help to make "border"-style default?

Edit: I would like to add three interesting articles, which also discuss the position of the icon and its iconography:

• https://www.viget.com/articles/testing-accordion-menu-designs-iconography/ being interpreted by https://uxmovement.com/navigation/where-to-place-your-accordion-menu-icons/ (n=140)
• https://www.nngroup.com/articles/mobile-accordions/

What I could read out: From a usability perspective a plus icon and the left side seems to be best according to the results presented in the study. However, the accordion elements in the study do not have frames either (corresponding to the "minimal"-style). In the compilation of the Nielsen Norman Group, on the other hand, a majority of the shown websites have the icon on the right side (Amazon among others), only Wikipedia positions the icons on the left side. For my personal (!) feeling, it's easier to scan the accordion titles if the icon is on the right side. :)

[kellychoffman]

Settings and flows feel like they are in a good place now. Nice!

Two more notes:

• Styles: I still feel like just adding a border isn't unique enough. One idea is to explore different layouts and ways to present this type of information. Another is size. Coblock's Shape Divider block is a fun examples to use that themes could then build on top of.
• Subjective / aesthetic / details: There's something about the arrow treatment that feels dated. More old school wp-admin than G2, if you will. Might be the size. Also, the position of the arrow when you add a border or background color to the header is too tight to the left.

[ZebulanStanphill]

It is worth noting that if the icon is on the right, it may be more difficult for the user to associate it with the title unless there is also a border around accordion title and icon.

[mapk]

This style variation incorporates the block's additional settings that allow it to visually differentiate from the default variation.

Style variation

• Larger heading text
• Gradient background in heading
• Custom color heading text
• Icon is right justified
• Borders with custom color

Block variation

Settings sidebar

• Styles
  • Minimal
  • Bold
• Accordion settings
  • [toggle] Open by default
  • [toggle] Animate opening
• Heading color settings
  • Text color
  • Background color
• Icon settings
  • [toggle] Move icon to other side
  • Select from a few icon choices

Inspector

[mapk]

I'm exploring a way to work in the icon settings into the block's toolbar.

[mariohamann]

Very nice! I wanted to add the idea of exactly those kinds of styles ("minimal" with icon on left and "extended" with icon on right and with borders) as well and am happy to see it here now. :) Thanks, @mapk !

[ZebulanStanphill]

I think some of these options ("Move icon to other side") are the kind of thing that should only be exposed at a global level, and never on a per-block basis. Allowing users to have accordions across their site using different values for options like those is a recipe for inconsistent design.

[mtias]

Agreed, that's been one of the most problematic parts of style variations, even with the "set by default". I think we need to be more meticulous with style variations until they can be represented fully through attributes, so that they can also be updated by the user / theme globally. We also need to be committed to maintaining the styles, which has created some issues with things like pullquotes.

[kellychoffman]

This was sort of what I was getting at with my comments on pushing the style options: to have the styles be a way to present an alternative layout (among other things). The "bold" style is getting there, but the gradient and color used have it appearing a bit too dated.

[mariohamann]

The "bold" style is getting there, but the gradient and color used have it appearing a bit too dated.

+1

Although I proposed to set some background for the heading area on hover or focus, I have the feeling there is currently too much styling by default. Maybe outlines with the plus on the right are enough as second style? I really liked the G2ish-feeling of the border-style in this draft:

https://user-images.githubusercontent.com/617986/90201664-5f2c7680-dd90-11ea-9169-f2f9fd8633d8.gif

Everything else could/should be styled by theme or FSE or whatever? :)

(I would like to add a visual draft on my own, but unfortunately I currently have only access to small iOS devices...)

[kellychoffman]

Technically anything can be done by themes or [insert manual way here] but it would be good if we created some nicely designed "head starts" for people that they could then further tweak as needed. IMO the border is not enough on its own but perhaps pairing that with an alternative layout would be 👍

[StaggerLeee]

I think it is wrong and confusing. Some basic design and CSS should be used for heading and content directly after chosing block type. As it is on GIF it strongly reminds of dealing just with simple Paragraph blocks.

[mapk]

@mariohamann, I hear you've got some time to begin development on this? Wonderful! Looking back on your comments above...

I decided early on to work with nested blocks

I'm not opposed to this. If you think it would work better, let's try it out. You bring up some positive points there.

I don't know how useful it is to position the unfolding icon on the left side by default. For example, if someone wants to include icons for orientation in their title, this will be difficult.

I prefer keeping aligned with the expanding icon on the left for now. Allowing users to add their own icon for each accordion element seems quite complex.

In your design @mapk it looks like the accordion_element in the editor is unfolded when it is selected. This was also the case in my projects at first. It is a common use case that content is written first, but only then is it decided to put it into an accordion. This makes it necessary to access the InnerBlock area of an accordion_element without the accordion_element being currently selected.

If we're building this out as one block with nested blocks, I understand. But I also imagined that if you were dragging content onto an accordion that was collapsed, it would open automatically to allow you to drop it in – similar to folders on an OS.

I therefore consider your older designs with the minimal border to be a much better default state and should still be minimal enough to make them customizable by themes. From a usability perspective, it will also only then become clear that the complete title section is clickable - which will hopefully be the case? :)

I'd really like to allow a super minimal design variation (no borders). Whether or not it's the default choice could be debatable.

Concerning the icon, I decided on a plus

Let's keep the triangle and include the + as an option. It looks like the Figma library has included a nice triangle in the icons file.

I'm looking forward to working with you on this! 👍

[mariohamann]

@mariohamann, I hear you've got some time to begin development on this?

@mapk "A little time" would fit better. ;) I am glad to be involved and I will try to do some work this weekend!

[mariohamann]

First of all, I would like to share the concept:

• accordion block (being a wrapper) with an <InnerBlocks />-component, only accordion-item-blocks allowed
• As many accordion-item-blocks as needed consisting of e. g. a -component (with no formatting options) and a <InnerBlocks />-component

Check out the following GIF to see the concept+example or try it out on CodePen. (I am not very happy with the transitions, but I don't think that's important at the moment. :)) (By the way: This a great example which would profit very much from https://github.com/WordPress/gutenberg/issues/25133 :))

The blocks I created rely on JavaScript, but at least they should be accessible as the function is based on W3 accordion example. I know, using JS is a big disadvantage. On the other hand there is at least one advantage: The editor can decide, whether accordion-items should close as soon as another accordion-item is being opened – a very frequently used function and in my opinion a Must-Have.

The JavaScript needs every accordion-item__button and accordion-item__content to be connected with their id and aria-controls/aria-labelledby. For this purpose I have used useInstanceId of the accordion-item.

[mariohamann]

@AlexChariyska DMed me on Slack and we discussed different things to get rid of JS in frontend. She had the idea of using hidden "checkbox" and "radio inputs". Both would allow accordions to have multiple (checkbox) or only single elements (radio) being open at the same time. At first it felt a bit hacky – but it works surpringly good. Here is a revised frontend prototype: https://codepen.io/mariohamann/pen/QWEErGQ

We are unsure whether this approach is accessible and would love to get some feedback e. g. from @ZebulanStanphill or @enriquesanchez. Of course feedback on the "checkbox/radio" proposal in general would be great, too.

[alexstine]

@mariohamann This is not accessible because you set "display: none;" on the input element. Screen readers would only hear the label announced which would not be valid for keyboard accessibility as it would not be focussable by default.

I recommend sticking with the JS front-end approach to toggle aria-expanded attribute. That is how I have always designed accordions and for this solution with checkboxes and radio buttons, I really don't see the big advantage of saving 1-2KB of JS.

Just my thoughts, thanks.

[mariohamann]

@alexstine Thank you very much for your fast and great feedback! I've changed the CSS a bit, so the checkbox is selectable. Sorry for this. After testing it again, I realised that the single elements now open and close by using the arrow down and up keys. I think this isn't standard behavior, is it?

Personally I would tend to use JS as well, especially as the JS of W3 seems to be proven accessible. But we couldn't think of any frontend JS in other core blocks and therefore are very unsure, if this should be the way to go. Maybe some other people being closer to the WP core could provide some feedback on this, too.

[alexstine]

@mariohamann It does not change with arrow up/down unless the screen reader is in edit/focus mode and attached to the radio buttons. This really just isn't good for UX though as SR users could get really confused if the radio buttons start changing due to the up/down arrow key presses. Most accessible way would be to use the buttons and then toggle aria-expanded.

Thanks.

[mariohamann]

Thanks again for your detailed and valuable insights!

So having discussed the following solutions:

1. <summary>/<details>: Not accessible enough and lacks accordion functionality (e. g. closing one item when another one is being opened)
2. checkbox/radio: Not accessible enough and tends to feel hacky
3. JS in Frontend: Provides JS in frontend, which is unusual for core blocks (edit: + core in general) at the moment, as far as I know.
4. Edit: Do not add "Accordion" to core and close the issue

Are there any other alternatives I didn't mention? If not, we would need a decision, if it's fine to use JS in frontend for this block.

[alexstine]

@mariohamann I cannot think of any more possible accessible implementations. Let's go with 3.

Thanks.

[mtias]

We can also not add this block in core