Accordion

[govuk-design-system]

Use this issue to discuss the accordion component in the GOV.UK Design System.

[frankieroberto]

I've done some work to extract the Accordion javascript from the Design Manual into a standalone component which no longer requires jQuery.

You can see the code here: https://github.com/frankieroberto/accordion

[tameemsafi]

Just a note that the DVSA heroku app link has a password. Below are the details:

username: admin
password: dvsa

Also source can be found here:
https://github.com/dvsa/front-end/blob/master/src/assets/js/dvsa/modules/accordions/accordion.js

[kr8n3r]

we're aiming for Service standard browsers support matrix right?

[timpaul]

Thanks @tameemsafi - I've updated the top comment with those details.

[frankieroberto]

@tameemsafi the DVSA components seems to have two versions, one with + and - icons, and the other with arrows. Have you tested both? Any reasons to prefer one over the other?

Also looks like your javascript does some scrolling, which I find slightly jarring, but perhaps there's a reason for this?

[tameemsafi]

@frankieroberto We did test both and the one with up/down arrows is the one that was chosen as it was more user-friendly. However, I put both in the styleguide just to show the different versions.

The scrolling feature works better if there is more content but I see what you mean that it looks a little annoying on the styleguide page.

You can see it being used live here:
https://www.check-mot.service.gov.uk/

[frankieroberto]

@tameemsafi interesting, thanks.

[fofr]

We're trying out a version of this in a form on "Find postgraduate teacher training courses":
https://search-and-compare-prototype.herokuapp.com/start/subjects (bat/beta)

[joelanman]

From Check MOT service:

[hannalaakso]

@frankieroberto has very kindly agreed to work with us on developing this component. The work will be based on https://github.com/frankieroberto/accordion

[hannalaakso]

Accordion component criteria

In addition to meeting the Design System criteria, we have agreed that this component will meet the following additional criteria:

Coding criteria

The accordion component must:

• be built using GOV.UK Frontend
• follow the GOV.UK Frontend coding standards
• have a Nunjucks macro
• have unit and integration tests
• be tested with these browsers
• be tested with these assistive technologies
• if appropriate, use Details disclosure element (this should be explored as part of the coding work)

Design criteria

The accordion component must:

• be usable on any screen size
• allow users to complete their task if JavaScript is not available
• change appearance when it is expanded/collapsed

Guidance criteria

The component guidance must:

• follow the GOV.UK Design System content pattern
• provide examples of common use cases
• describe what research has been done and what still needs to be done
• follow the GOV.UK style guide

Research criteria

The contributor must:

• have collected at least 3 different examples of accordions being used in services on GOV.UK
• have tested with a representative range of users, including those with disabilities, in a prototype or live service OR
• be able to show that the component is clearly based on relevant user research from other organisations and best practice (in this case, the component would be published as experimental)

Accessibility criteria

• must meet WCAG 2.0 AA guidelines
• not depend on colour to communicate information
• handle cases where user changes their default colours
• it must be possible to focus on the controls using the tab key
• the controls must change in appearance when keyboard focus moves to it
• it must be possible to activate the controls using the appropriate keys
• the controls must indicate when the mouse is hovered over it
• it must be possible to activate the accordion controls using a click
• the controls must be large enough to tap accurately with one finger
• it must be possible to activate the controls using voice commands (see Coding criteria).
• the expanded/collapsed state must be available to screen readers
• the relationship between the accordion controls and disclosed content must be available to screen readers
• it must be possible to focus on the accordion controls using standard screen reader button commands
• the controls must have a visible text label
• the contrast between the accordion text label and its background must meet (or exceed) a ratio of 4.5:1
• the markup must validate against HTML5 validator
• the content must be in a logical order in the source code

[ignaciaorellana]

This contribution in being worked on GOV.UK Frontend by @frankieroberto, see further details here: alphagov/govuk-frontend#958

[joelanman]

Interesting thread on the Australian design system

[frankieroberto]

The Worldwide section of GOV.UK uses accordions on the country pages, eg:

[adamsilver]

This looks really good—nice one, Frankie!

Here’s some notes/questions:

1. There’s a typo in the Nunjucks macro documentation: it says “Required. undefined See items”

2. Is “Open all” clear enough for screen reader users? I wonder if it should have “sections” (or similar) added to the end using visually hidden? Same for “Close all”

3. Is the “Open all/Close all” toggle button text configurable?

4. Hover state: is the subtle change of background colour obvious enough? We had a subtle grey used on Tabs (Tabs #100 (comment))

5. Can it be configured so that particular sections start open?

6. Can it be configured so that all sections start open?

7. The focus outline only surrounds the button on the left even though the entire row is clickable. Is there a reason for this? I’d suggest the whole thing gets the focus outline.

8. Further to (7) could the <button> wrap the entire row contents including the H2 and SVG icon.

9. Could you add focusable=false to the SVG so that it’s not part of the tab sequence?

10. Could you add a visually-hidden class to the SVG so that it’s not read out for screen reader users as the <button> seems to provide enough information?

11. While forms shouldn’t be used with accordions, there is a potential need to have form controls inside an accordion like this for filtering controls. See the following links:

• http://nostyle.herokuapp.com/examples/filter-form
• Accordion #1 (comment)

12. With the filters, it's worth noting that the accordion label/heading is actually a legend. I wonder if we can make the accordion component work on legends etc.

13. There is a bug, at least in the second example where the <h2> contains the <button> and then another <h2> inside it.

14. Can it be configured so that the accordion doesn't have the “Open all” button?

[adamsilver]

@dashouse Hey Dave. @frankieroberto asked me to do this on Monday so I duplicated my comment on the PR: alphagov/govuk-frontend#958

[miaallers-zz]

I have a comment on the placement and use of the 'plus' signs/ arrows:

• I'm not convinced that a plus sign or arrow necessarily has enough affordance for low confidence users
• The placement of the arrows to the far right of each section might make it invisible for users who use screen magnification
• Ditto the placement of the 'open all' element
• Using a word such as 'open', which refers to the interaction itself, may be confusing for screen reader users (who would not see anything opening). It may make more sense to use a word such as 'show', which explains the intent of the interaction, and does not describe the interaction

The way that we dealt with these issues on the GOV.UK Step by Step accordion was to use descriptive link text beneath the section headings:

(Please note that the placement of the 'show all' link should ideally be on the far left to accommodate magnified screen use. It just hasn't been implemented yet!)

[adamsilver]

@miaallers great feedback.

Thanks to your comment, I've just realised that the step by step pattern is basically an accordion but with numbers (and a connecting line). That's pretty cool and wonder if this could end up being the same pattern (or reusing what's under the hood) somehow.

In the screenshot, the “Show all” text is also aligned right and may be problematic for people using a magnifier (like you said). Did you do any testing around this?

[adamsilver]

@frankieroberto did you consider using several instances of the Details component as a style for the accordion?

[gillick]

We’ve updated the accordion component

We’ve released an improved accordion component to be more accessible and consistent with the rest of the Design System.

...

Hello! I manage a few websites that run a "cousin" design system from across the pond and it seems that we share a "love" for accordions. I'm wondering if you've been looking into an issue that's been bugging me -- the inability to "link to highlight" to something inside an accordion. There's also the inability to use ctrl-f, but I'm willing to bet you've already had that conversation.

Apologies if I'm posting in an inappropriate location.

BTW, I love your work and generally direct colleagues to your guidance documents -- especially for best advice on using accordions.

[vanitabarrett]

Hi @gillick, thanks for getting in touch! It's not something we've considered recently for the accordion. We do have the option to open sections by default, but not to link to something inside an accordion section. We actually have an open issue for that: alphagov/govuk-frontend#1581 but it's not an issue that has been reported frequently by users so it's not been prioritised.

[calvin-lau-sig7]

Hello from me as well @gillick! Thanks for the kind words.

To be honest, I'd perhaps describe our relationship with accordions as "it's complicated." They can be useful to help users pick and choose the information they need, but we also see instances where accordions are used to hide messy information that just needs to be organised better.

That's why we include guidance on When not to use an accordion in our guidance for the component.

In cases where you'd like to "link to highlight" or link to something inside an accordion section, we'd suggest considering if it should be moved outside of the accordion, since it's likely to be important enough to not have hidden from users.

Hope that's helpful.

[gillick]

Thanks, @calvin-lau-sig7 and @vanitabarrett! It's possible that my "love" quotes weren't as clear as they could be, so I'm going to adopt "it's complicated" for the duration. Let's just say that I've shared your When not to use an accordion guidance at least twice in the past fortnight. I especially appreciate that your design system (and therefore the guidance) keeps the when to / when not to guidance visually prominent. There's also the fact that you follow what my team calls the "League of Legends" rule and doesn't spoil a good explanation with a bad example. A hat tip to your team.

TBH, I was hoping for a tech answer to accordion issues because the human-factors answer (craft better stuff) is a challenge to enforce. Well, at least we're all in the same boat -- and paddling in the same direction.

Good luck -- and if I can ever be of service (or provide a good pizza recommendation in the DC metro), just ping.

[TautvydasPocius]

Hello, is this component ready for production use on a service which is not allowed to use javascript and is multi-lingual? Considering that this component is expiremental as of now would it be best to use an alternative?

[vanitabarrett]

Hi @TautvydasPocius . The accordion component can be used for services in production, although I would encourage you to read the guidance on the Design System website (specifically 'when to use this component') as it's not suitable for all scenarios. Just to be clear - services are allowed to use JavaScript, but there should be a fallback (i.e: it should still work if JavaScript is not available). The accordion component has been built using progressive enhancement, so if a user does not have JavaScript available, the content inside the accordion will display on the page by default instead.

We're aware that the accordion, and some other components in GOV.UK Frontend, do not support customisable text (including translations) and this is something the team will be investigating over the next few months.

The team is also aware that our 'experimental' label is unclear and we will be revisiting our use of that label in future.

[cjforms]

@TautvydasPocius
I'm not part of the Design System team so I can be very clear:

Do not use an accordion.

In the guidance, you will see a long list of problems and things that can go wrong with this component, But the most important one for your service, which is not allowed to use Javascript, is this one:

"The accordion component uses JavaScript. When JavaScript is not available, users will see all the content displayed with the section labels as headings."

So your users will see section labels as headings, so forget about accordions and work with section labels as headings instead. When you test the page, if your users are finding that it is too long to cope with then try one or more of these strategies:

• simplify and reduce the amount of content
• split the content across multiple pages
• use a list of links at the start of the page (known as ‘anchor links’) to take the user to particular sections of a page

This component gets far too much attention because it happens to start with an A so appears at the top of alphabetical lists of components.

Related: @amyhupe and I wrote a joint blog post about long pages
On my website: https://www.effortmark.co.uk/dont-be-afraid-of-the-big-long-page/
On her website: https://amyhupe.co.uk/articles/dont-be-afraid-of-the-big-long-page/

[Zainzzkk]

Hi,

Sorry if this is the wrong place to write this issue I am having. I am using this accordion component and having issues with it remembering expanding selection between different sessions.

Example, select "show all sections" clicked on a deal. Insert new deal and go to page with accordion on a different url-> all sections are expanded. Press "hide all sections" and insert a new deal and navigate to it on a different url and all sections are closed. Repeat.
I have set expanded: false in items and have kept it as false to try and force it to be closed but it doesn't seem to work.

[frankieroberto]

@Zainzzkk the 'remembering' of accordion state is stored against the value of the id attribute on the accordion. So if the accordion on a template is used across multiple URLs, you should make sure that the id is unique to that URL.

For example:

<div class="govuk-accordion" data-module="govuk-accordion" id="deal-{{ $id_of_deal }}">
  [...]
</div>  

The expanded: true and expanded: false setting only sets the initial state if no state has been remembered....

Hope that helps!

[injms]

The hidden="until-found" attribute looks to be an interesting new feature that the accordion could benefit from in a backwards compatible manner:

By adding hidden=until-found to the container for your hidden content, you make it possible for the browser to search text in that hidden region, and reveal the section if a match is found.

https://developer.chrome.com/blog/hidden-until-found/

[edwardhorsford]

I wanted to share a real-world example of how the new accordion design looks compared to previously. For our use case, I think the old design works better because of the nature of the usage and the more compact appearance.

Our use case has an accordion section for each month of the year - 12 months in total - with a table within each section. There'll always be twelve sections to the accordion, but the data within might vary quite a bit.

I think the old design is easier to scan - subjectively as it's just a list of dates they flow on from each other better than the revised design. I think a lot of this is the height of each section - which has gone from 61px to 114px - an 87% increase.

Old accordion design:

New accordion design:

[edwardhorsford]

I have a hacky solution if you're having issues testing whether the right accordions are defaulting to open and shut because the accordion is remembering your previous selections:

The js remembering the selections works using the id of the accordion. If you wanted to stop all the persistence stuff could add a random number to the end of the id - this way it would be unique each time. You could use a similar thing to make sure it got remembered for no more than a day by appending the current date to the id.

[stagarz]

I agree with @edwardhorsford, content is now much harder to scan and significantly more scrolling is required to get through the same amount of information. Especially for internal services, where users are expected to interact with complex data on a daily basis, the accessibility tradeoff doesn't hold up.

Is there a chance to have the old design back for internal services please?

[querkmachine]

Hi @edwardhorsford and @stagarz,

Thanks for your feedback. We had a short discussion about this within the team last week.

In short, we don't consider this to be a priority. The new accordion design has been thoroughly tested with users (including those with access needs), tested with assistive technologies, and reviewed by accessibility experts. The new implementation is WCAG compliant; the old implementation was not.

Although we are aware and accept that the new accordion is harder to scan and takes up more vertical space, we consider these to be reasonable trade-offs for the sake of making the accordion accessible. We don't feel like there is a compelling reason to make changes to the design at this time, especially as many of the accessiility problems with the original version were visual in nature.

We are confident that the new design is a marked improvement on the original. We encourage implementors to really think about the compromises needed to continue using the older design and to carry out user testing on anything new (or old, in this case). If you do carry out testing (ideally including assistive technology users) then we'd be interested in seeing it!

[MalcolmVonMoJ]

Our content designers requested that direct-linking to an element ID within the accordion should open that section immediately. Therefore, I have written this JavaScript to achieve that:

function haleAccordionDirectID() {
	if (window.location.href.split("#").length == 2) {
		
		// Split the string and get the ID
		const halePageRequestedID = window.location.href.split("#")[1];

		// Check for the requested ID within the accordion
		if (document.querySelector(".govuk-accordion__section #" + halePageRequestedID) !== null) {

			const haleRequiredSection = document.getElementById(halePageRequestedID).closest(".govuk-accordion__section");
			haleRequiredSection.classList.add("govuk-accordion__section--expanded");

			haleRequiredSection.scrollIntoView();
		}
	}
}

It is yet to be reviewed by our other developers, but I thought I'd share it here before I forget.

[36degrees]

@MalcolmVonMoJ as well as adding the --expanded modifier class, there's also quite a lot of other things that the component does when showing and hiding sections, including:

• updating the text and icon used for the 'Show / Hide' for the section
• updating the text and icon for the 'Show / Hide all sections' button
• setting the aria-expanded attribute on the button so that the expanded state is correctly communicated to users of assistive tech such as screen readers

Without also taking care of these things the various bits of the interface are likely to get out of sync, and the expanded state will not be communicated correctly to assistive tech users.

[MalcolmVonMoJ]

Thanks for replying Ollie. Originally I thought that would be the case. But it was pointed out to me that if I only add --expanded then those other things are dealt with by the existing JavaScript (lines 261-264).
My new JS is running first, and it seems to work locally.
If I'm missing something, please say.

[nick-golding-softwire]

I have a use case which I believe is similar to @edwardhorsford's comment above on 17th May.

It's not a public-facing service; the users are local authority staff in a role requiring some data processing expertise. We are supplying them an error report for a spreadsheet of data they've uploaded; there could be many errors in each of many rows in the spreadsheet.

Ideally I'd like the first thing they see to be an overview, where each row in the spreadsheet has one row in the overview that summarises how many errors there are in that row but without going into detail. Then I'd like the user to be able to expand each row to see the full details of the errors in it.

Hopefully that description makes sense. It seems to me that the "old" design Ed refers to - which I haven't used before - is a better pattern for this than the new one, as there could be dozens of rows (accordion sections) and the new accordion design would take up a lot of space, be daunting to users, and be very hard for a user to scan to get that overview of the report.

Are the "old" accordion designs / macros available somewhere for my team to implement and test? (We would look into the accessibility issues at the same time and aim to test with assistive technology users. If there's a summary of the issues somewhere that would help us ensure we're addressing the right things.)

Alternatively if there's a better pattern for our use case then I'm very open to recommendations!

[patrickhlauke]

Arguably, using aria-expanded as well as changing the actual text of the buttons ("Show" / "Hide") leads to confusing announcements, along the lines of Writing well for specialists , Show this section collapsed / Writing well for specialists , Hide this section expanded.

I'd say either use aria-expanded, or change the text.

[patrickhlauke]

Currently, the demo at https://design-system.service.gov.uk/components/accordion/ uses :focus, rather than :focus-visible. As a result, the rather heavy "yellow/orange background and thick underline" styling is applied as a result of a mouse click (in anything other than Safari), which is visually confusing for mouse/pointer users I'd say.

[CharlotteDowns]

We have removed the 'Experimental' tag from components, patterns, and guidance in the Design System 😌.

The tag was being used on the Accordion component to raise awareness that more research is needed to validate it. However, we recently published new guidance on how to share findings from users which we hope will make it easier to collect more information about how our Design System is being used across services.

If your team has used this component please let us know 💪🏻.

[Jeff-Cuss]

Was there a stage in the development of this component where the following choice was made?
Either:
The 'Show all sections' control becomes 'Hide all sections' when the user has opened one or more sections of the accordion.
Or:
The 'Show all sections' control does not become 'Hide all sections' until the user has opened all the sections of the accordion - like it is now?

I'm keen to hear if there was any research or user testing around this issue.

Sorry if it's in here somewhere already, I have tried to find it!