ba-accordion
We use accordions to hide or show content under an interactive heading
Airframe
Web Components
React
React Native
Picking between ba-details and ba-accordion
Use ba-accordion when:
- The text in the closed state acts as a heading for the content it contains
- You need something more prominent
- Grouping many collapsible sections
Use ba-details when:
- There is a small amount of content to be disclosed
- You need something less prominent
- The collapsible section is standalone
Anatomy
Heading
Clearly labels the main topic or section of the accordion so users can quickly understand its purpose
Subheading (optional)
Provides supporting context or a short description to help users better understand the accordion section
Accordion header
The interactive header area that contains the section label and expand or collapse control, allowing users to toggle the visibility of the content
Accordion content
The expandable area that reveals additional content, such as text, layout, or other components, when the accordion is opened
Design Documentation
When placing accordions always match the width to the preceding elements, i.e. header or paragraph, following the layout rules.
On mobile any of the accordions should extend to the whole 12 columns. On desktop they should never be smaller than 3 columns.
When there are many accordions grouped together it's tempting to only allow one accordion to be open at a time. However this does not provide the best user experience:
- On mobile devices auto closing can interfere with the scroll behavior
- Automatically moving the user up and down the page can be disorientating
- Increases cognitive load of having to remember what was in a closed accordion
- It makes it hard to compare the contents of multiple accordions
Further reading:
The content in ba-accordion is intended for information that not every user needs. Therefore, it should remain closed until the user interacts with the component.
If you are considering opening ba-accordion by default, the content might be better placed directly on the page instead of inside the ba-accordion
If the content is required by every user, then it should be placed directly on the page rather than in a ba-accordion component. This ensures that all users can access the information without needing to interact with an additional component.
Live Demo
Accordion content
Accordion content
Accordion content
<ba-accordion heading="Accordion 1">
<ba-content>
<p>Accordion content</p>
</ba-content>
</ba-accordion>
<ba-accordion heading="Accordion 2">
<ba-content>
<p>Accordion content</p>
</ba-content>
</ba-accordion>
<ba-accordion heading="Accordion 3">
<ba-content>
<p>Accordion content</p>
</ba-content>
</ba-accordion>Properties and attributes
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
attentionIndicator |
attention-indicator |
Show the attention indicator on the heading | boolean | undefined |
undefined |
attentionIndicatorText |
attention-indicator-text |
Text to explain to screen readers that this accordion requires attention | string | undefined |
undefined |
dropShadow |
drop-shadow |
Toggles a drop shadow on the accordion | boolean | undefined |
false |
heading(required) |
heading |
Sets the accordion heading, this will populate the heading within the accordion | string |
undefined |
headingLevel |
heading-level |
Sets the accordion headingLevel, this will populate an |
2 | 3 | 4 | 5 | 6 | undefined |
2 |
open |
open |
Sets the open state | boolean | undefined |
false |
subheading |
subheading |
Sets the accordion sub heading | string | undefined |
undefined |
Permitted ARIA roles
- None
Slots
| Slot | Description | Permitted elements |
|---|---|---|
| Unnamed slot | Elements will render in the body of the component | <ba‑content>, <ba‑flex>, <ba‑form‑group>, <ba‑form‑group‑dropdown>, <ba‑grid>, <ba‑input>, <ba‑input‑date>, <ba‑input‑datepicker>, <ba‑input‑email>, <ba‑input‑number>, <ba‑input‑password>, <ba‑input‑phone‑number>, <ba‑input‑secure‑field>, <ba‑input‑stepper>, <ba‑input‑text>, <ba‑input‑textarea>, <ba‑input‑typeahead>, <ba‑input‑upload>, <ba‑message>, <ba‑radio‑group>, <ba‑select>, <fieldset>, <form> |
Parent components
ba-accordion can be slotted into:
Events
| Event | Description | Type |
|---|---|---|
baBlur |
Emitted when the toggle loses focus. | CustomEvent<void> |
baFocus |
Emitted when the toggle has focus. | CustomEvent<void> |
Usage
Basic usage
Most scenarios will only require the heading attribute and some content
<ba-accordion heading="accordion heading">
<ba-content>
<p>Accordion content</p>
</ba-content>
</ba-accordion>Setting heading level
The heading level can be set by passing a number to the heading-level attribute. The heading level should be set by the preceding heading on the page. Headings within the accordion should start at 1 level lower than has been set in the heading-level attribute.
<h2>A heading further up on the page</h2>
...
<ba-accordion heading="accordion heading" heading-level="3">
<ba-content>
<h4>A heading inside the accordion</h4>
<p>Accordion content</p>
</ba-content>
</ba-accordion>Using multiple accordions
When you place several accordions in a column, the first accordion has no top margin, and every accordion that follows automatically gets a top margin added.
That spacing is added with the CSS selector ba-accordion + ba-accordion, so two accordions must sit directly next to each other in the markup. If you wrap an individual ba-accordion in another element (for example, a <div>), the selector no longer matches and the automatic margin disappears.
<ba-accordion heading="accordion heading">
<!-- has no top margin -->
...
</ba-accordion>
<ba-accordion heading="accordion heading">
<!-- has top margin -->
...
</ba-accordion>
<ba-accordion heading="accordion heading">
<!-- has top margin -->
...
</ba-accordion>With a drop shadow
The accordion component can also be rendered with a drop shadow to give the component some depth
<ba-accordion heading="Accordion 1" drop-shadow>
<ba-content>
<p>Accordion content</p>
</ba-content>
</ba-accordion>Guidelines
It's important to maintain the order of headings so that they appear in a logical order in the page. Screen readers (and other assistive technology) rely on headings to navigate and understand structure of pages.
Further reading:
Keyboard navigation
State: Previous element in DOM has focus
<button> in shadow DOM gets focus
State: <button> in shadow DOM has focus
Toggles the open/close state of the accordion
Toggles the open/close state of the accordion
State: <button> in shadow DOM has focus and the accordion is closed
Next tabbable element outside of the accordion gets focus
State: <button> in shadow DOM has focus and the accordion is open
Next tabbable element inside of the accordion gets focus. Or if there are no tabbable elements inside the accordion, the next tabbable element outside of the accordion gets focus
State: Last tabbable element inside the open accordion has focus
Next tabbable element outside of the accordion gets focus
Usage and accessibility checklist
Use this checklist to confirm the component has been configured and used correctly.
UX checklist
- ba-accordion matches the width of preceding elements (header or paragraph) following layout rules
- On mobile, ba-accordion extends to the full width of the screen
- On desktop, ba-accordion is never smaller than 3 columns
- Multiple accordions can be open at the same time when grouped together
- ba-accordion is always closed by default
- ba-accordion is only used for optional information, not content required by every user
- If considering opening by default, evaluate if content should be placed directly on the page instead
Accessibility checklist
- Use the heading-level attribute to maintain proper heading hierarchy in the page
- Heading follows the correct document hierarchy
- ba-accordion has discernible text
- Focus indicator has not been obscured on all sides of the component
- ba-accordion is not nested inside other interactive elements
These checks are handled by the component and do not need to be repeated each time it is used.
- ba-accordion is operable using assistive technology
- Open and closed states are available to assistive technology
- Has a visible focus indicator on all sides of the component
- Colour contrast for all states in all BAgel themes
- Animations respect users' reduced motion settings
- High contrast mode adjustments