Expandable sectionStatusrelease

Show and hide a section of content

Guidance

Use this pattern for toggles and accordions that expand and collapse content into in the document flow. This is an alterantive to the HTML details element which has some accessibility issues and constraints (see references below).

Example

Open in a new tab

Dependencies and installation

Package	Installation
@stormid/toggle	`npm i -S @stormid/toggle`

Code

<div class="expandable-section"><h2 class="expandable-section__heading"><button type="button" class="expandable-section__btn js-expandable-section__btn-1" aria-expanded="false" aria-controls="section-1">Section title</button></h2><div id="section-1" class="expandable-section__bd js-expandable-section" data-toggle="js-expandable-section__btn-1"><p>Aenean id posuere nunc. Donec diam nisl, rhoncus vel faucibus sed, porttitor sit amet ipsum. Donec at venenatis augue. Phasellus consequat lectus non augue vestibulum, at varius diam sagittis. Morbi nec purus augue. Etiam rutrum ullamcorper arcu vitae sollicitudin. Aliquam bibendum suscipit risus, at lacinia tortor efficitur ac.</p><p>Praesent vitae mi nec mauris vehicula ultricies nec ut felis. Nam vel nisi id nunc efficitur fermentum. Vestibulum mollis enim nec ultrices mattis. Curabitur placerat sed nisl lobortis iaculis. Fusce porttitor massa augue, sit amet faucibus enim finibus nec. Maecenas hendrerit metus in justo commodo viverra.</p></div></div><div class="expandable-section"><h2 class="expandable-section__heading"><button type="button" class="expandable-section__btn js-expandable-section__btn-2" aria-expanded="false" aria-controls="section-2">Section title</button></h2><div id="section-2" class="expandable-section__bd js-expandable-section" data-toggle="js-expandable-section__btn-2"><p>Aenean id posuere nunc. Donec diam nisl, rhoncus vel faucibus sed, porttitor sit amet ipsum. Donec at venenatis augue. Phasellus consequat lectus non augue vestibulum, at varius diam sagittis. Morbi nec purus augue. Etiam rutrum ullamcorper arcu vitae sollicitudin. Aliquam bibendum suscipit risus, at lacinia tortor efficitur ac.</p><p>Praesent vitae mi nec mauris vehicula ultricies nec ut felis. Nam vel nisi id nunc efficitur fermentum. Vestibulum mollis enim nec ultrices mattis. Curabitur placerat sed nisl lobortis iaculis. Fusce porttitor massa augue, sit amet faucibus enim finibus nec. Maecenas hendrerit metus in justo commodo viverra.</p></div></div>

import toggle from '@stormid/toggle';

toggle('.js-expandable-section, { focus: false, local: true });

Acceptance criteria

The following is a list of example acceptance criteria to test against when using this pattern. These critera should test that the specific markup requirements are met, and that the expanding section behaves visually and functionally as expected.

For validation in developer tools / web inspector

An HTML
```
<button>
```
element is used to expand/collapse the section
An
```
aria-expanded
```
attribute should be present on the toggle
```
<button>
```
. The value of this should be 'true' when the section is expanded, and false when the section is collapsed.
The toggle
```
<button>
```
element should have an
```
aria-controls
```
attribute. The value of this should match the ID of the section being expanded/collapsed.

For visual validation

Section toggle buttons should have a clearly visible focus style which meets accessibility contrast requirements
Section toggle buttons should be no less than 44px x 44px in size (unless any of the allowed WCAG exceptions apply)
Section toggle buttons should be appropriately labelled to describe their functionality. If the design requires no visible text, a label should be added as an
```
aria-label
```
attribute on the
```
<button>
```
element
The collapsed section should be hidden visually, hidden from keyboard access, and not read by screen readers
The expanded section should be visible, available for keyboard access, and read by screen readers

For functional validation

Section toggle buttons should be available to be tabbed to and activated via keyboard

UI Patterns