Accordion

A dropdown mechanism that allow users to either show or hide related content.

Example

Default Accordion

This is the first item's accordion body. It is shown by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go within the .accordion-body, though the transition does limit overflow.

This is the second item's accordion body. It is hidden by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go within the .accordion-body, though the transition does limit overflow.

This is the third item's accordion body. It is hidden by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go within the .accordion-body, though the transition does limit overflow.

HTML React Web Component
<div class="sgds accordion" id="accordionExample">
    <div class="accordion-item">
        <h2 class="accordion-header" id="headingOne">
            <button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#collapseOne"
                aria-expanded="true" aria-controls="collapseOne">
                Accordion Item #1
            </button>
        </h2>
        <div id="collapseOne" class="accordion-collapse collapse show" aria-labelledby="headingOne"
            data-bs-parent="#accordionExample">
            <div class="accordion-body">
                <strong>This is the first item's accordion body.</strong> It is shown by default, until the collapse
                plugin adds the appropriate classes that we use to style each element. These classes control the overall
                appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with
                custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go
                within the <code>.accordion-body</code>, though the transition does limit overflow.
            </div>
        </div>
    </div>
    <div class="accordion-item">
        <h2 class="accordion-header" id="headingTwo">
            <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse"
                data-bs-target="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo">
                Accordion Item #2
            </button>
        </h2>
        <div id="collapseTwo" class="accordion-collapse collapse" aria-labelledby="headingTwo"
            data-bs-parent="#accordionExample">
            <div class="accordion-body">
                <strong>This is the second item's accordion body.</strong> It is hidden by default, until the collapse
                plugin adds the appropriate classes that we use to style each element. These classes control the overall
                appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with
                custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go
                within the <code>.accordion-body</code>, though the transition does limit overflow.
            </div>
        </div>
    </div>
    <div class="accordion-item">
        <h2 class="accordion-header" id="headingThree">
            <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse"
                data-bs-target="#collapseThree" aria-expanded="false" aria-controls="collapseThree">
                Accordion Item #3
            </button>
        </h2>
        <div id="collapseThree" class="accordion-collapse collapse" aria-labelledby="headingThree"
            data-bs-parent="#accordionExample">
            <div class="accordion-body">
                <strong>This is the third item's accordion body.</strong> It is hidden by default, until the collapse
                plugin adds the appropriate classes that we use to style each element. These classes control the overall
                appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with
                custom CSS or overriding our default variables. It's also worth noting that just about any HTML can go
                within the <code>.accordion-body</code>, though the transition does limit overflow.
            </div>
        </div>
    </div>
</div>
View on React storybook View on Web component storybook

Anatomy

Closed

Closed Accordion Anatomy
  1. Text: Serves to tell users what the accordion is being used for.
  2. Container: Encloses the content within, width and height to be adjusted according to content.

Open

Open Accordion Anatomy
  1. Text: Serves to tell users what the accordion is being used for. Bold when the accordion is open.
  2. Container: Encloses the content within, width and height to be adjusted according to content.
  3. Content: Content should be kept as short and to the point as possible to help with scanning.

Spacing

Accordion Spacing

Within the accordion button
Ensure that there is a min of 24px horizontal spacing and 16px vertical spacing.

Within the accordion
Ensure that there is a min of 24px spacing within the accordion, and 16px vertical spacing between the accordion title and content.

Usage guidelines

Best practices:

  1. Accordion labels should not link to a page; labels and buttons should open the same thing. (e.g. your label should not link to another page, and your icon opens the accordion).

Accordion should be used when:

  1. There is insufficient space within the page to display the necessary information.
  2. Users require an overview of specific content that's related to one another.

Accordion should not be used when:

  1. Each section only contains a small amount of text or a few elements, an accordion can unnecessarily complicate the layout. Simple lists or headings might work better.
  2. User needs to see all information in a single page.
  3. The user wants to compare information in a single layout.

Usability guidelines

Do ensure that the entire heading is clickable to the user
A larger target will make it easier for users to manipulate.

Ensure enough space between content and headings
This is to prevent the user from accidentally closing the accordion.

Behaviour
In addition to the collapse and expanded states, accordions should also have interactive state for focus. User should be able to trigger a state change by clicking anywhere in the header area.

Accessibility guidelines

Aria attributes

  1. The accordion header has a role of <button>, with an aria-expanded attribute set to "true" or "false".
  2. The button has an aria-controls property set to the unique id of the panel it controls.

Keyboard accessibility

Ensure that the accordion can be navigated and operated using the keyboard:
  1. Tab or Shift-Tab to navigate between accordion headers.
  2. Enter or Space to expand or collapse sections.

Focus indicator

  1. Focus indicator should be clearly visible when a header is focused.
  2. Move focus to the accordion content when it is expanded, if necessary.
  3. Ensure that focusable elements within the accordion panel can be navigated using the keyboard.

Accordion design tokens

$accordion-padding-y: 1rem !default;
$accordion-padding-x: 1.25rem !default;
$accordion-color: $body-color !default;
$accordion-bg: $body-bg !default;
$accordion-border-width: $border-width !default;
$accordion-border-color: $border-color !default;
$accordion-border-radius: $border-radius !default;
$accordion-inner-border-radius: subtract($accordion-border-radius, $accordion-border-width) !default;
$accordion-body-padding-y: $accordion-padding-y !default;
$accordion-body-padding-x: 1.5rem !default;
$accordion-button-padding-y: $accordion-padding-y !default;
$accordion-button-padding-x: 1.5rem !default;
$accordion-button-color: $accordion-color !default;
$accordion-button-bg: $accordion-bg !default;
$accordion-transition: $btn-transition, border-radius .15s ease !default;
$accordion-button-active-bg: none !default;
$accordion-button-active-color: $purple-500 !default;
$accordion-button-focus-border-color: $input-focus-border-color !default;
$accordion-button-focus-box-shadow: $btn-focus-box-shadow !default;
$accordion-icon-width: 1.25rem !default;
$accordion-icon-color: $accordion-button-color !default;
$accordion-icon-active-color: $accordion-button-active-color !default;
$accordion-icon-transition: transform .2s ease-in-out !default;
$accordion-icon-transform: rotate(-180deg) !default;
$accordion-button-icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'
    fill='#{$accordion-icon-color}'>
    <path fill-rule='evenodd'
        d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z' />
</svg>") !default;
$accordion-button-active-icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'
    fill='#{$accordion-icon-active-color}'>
    <path fill-rule='evenodd'
        d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z' />
</svg>") !default;

Last updated 02 October 2024
Home


Latest version 2.3.5