ba-accordion

We use accordions to hide or show content under an interactive heading

Figma

GitHub

Storybook

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

Live Demo

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>

Guidelines

When placing accordions always match the width to the proceeding 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.

Mobile layout and desktop minimum size

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

Accessibility

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.

Key	Element	State	Behaviour
`Enter`	`<button>`	Button has focus	Toggles the open / close state of the accordion
`Space`	`<button>`	Button has focus	Toggles the open / close state of the accordion

Code

Properties & 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 within the accordion	`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`

Events

Event	Description	Type
`baBlur`	Emitted when the toggle loses focus.	`CustomEvent<void>`
`baFocus`	Emitted when the toggle has focus.	`CustomEvent<void>`

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‑stepper>`, `<ba‑input‑text>`, `<ba‑input‑textarea>`, `<ba‑input‑typeahead>`, `<ba‑input‑upload>`, `<ba‑message>`, `<ba‑radio‑group>`, `<ba‑select>`, `<fieldset>`, `<form>`

Permitted ARIA roles

None

Parent components

ba-accordion can be slotted into:

Usage

Basic usage

Most scenarios will only require the heading attribute and some content

A simple accordion

<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 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.

The heading level has been set to 3 so that it appears below the <h2> in the document outline

<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.

Three stacked accordions

<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.

An accordion being rendered with a drop shadow

<ba-accordion heading="Accordion 1">
  <ba-content>
     <p>Accordion content</p>
  </ba-content>
</ba-accordion>