Skip Navigation

Photo by Sara Codair  on Unsplash

Accordions

Accordions are useful when a page covers several different topics. A good example would be an FAQ page. It's best to avoid using accordions to make long pages appear shorter.

Accessibility Spotlight

All focusable elements in the accordion are included in the page tab sequence.

Accordions have keyboard support including Tab and up and down arrows.

When focused, accordion headers expand the panel with space or enter keys.

When clicked, accordion headers toggle the appropriate aria-hidden and aria-expanded attributes.

Default Behavior

The following is a basic accordion component. All accordion panels are closed by default.

The monarch butterfly or simply monarch is a milkweed butterfly in the family Nymphalidae. Other common names, depending on region, include milkweed, common tiger, wanderer, and black veined brown. It may be the most familiar North American butterfly, and is considered an iconic pollinator species.

The black swallowtail, American swallowtail, or parsnip swallowtail, is a butterfly found throughout much of North America. It is the state butterfly of Oklahoma and New Jersey.

The cecropia moth is North America's largest native moth. It is a member of the family Saturniidae, or giant silk moths. Females have been documented with a wingspan of five to seven inches or more.

The elephant hawk moth or large elephant hawk moth, is a moth in the family Sphingidae. Its common name is derived from the caterpillar's resemblance to an elephant's trunk. It is most common incentral Europe and is distributed throughout the Palearctic region.

The spicebush swallowtail or green-clouded butterfly, is a common black swallowtail butterfly found in North America. It has two subspecies, Papilio troilus troilus and Papilio troilus ilioneus, the latter found mainly in the Florida peninsula.

<div class="accordion">

    <button
        class="accordion__button h5"
        id="acc-button-example-01"
        data-accordion="button"
        aria-controls="acc-panel-example-01"
        aria-expanded="false">
            Danaus Plexippus
    </button>

    <div
        class="accordion__panel"
        id="acc-panel-example-01"
        data-accordion="panel"
        aria-labelledby="acc-button-example-01"
        role="region">

        <div class="accordion__panel__content">
            <p>
                The monarch butterfly or simply monarch is a milkweed butterfly in the family Nymphalidae. Other common names, depending on region, include milkweed, common tiger, wanderer, and black veined brown. It may be the most familiar <a href="#1">North American</a> butterfly, and is considered an iconic pollinator species.
            </p>
        </div>

    </div>

    <!-- Repeat pair above as needed -->
</div>
Figure 1
Line #Details
1

The parent .accordion class is required.

This selector uses JavaScript to group a set of topics (accordion headers) with one another.

3-10

The child .accordion__button selector is required.

The id attribute equals the value of its associated panel's aria-labelledby attribute.

The data-accordion="button" attribute is present on the accordion button for JavaScript purposes.

The aria-controls attribute equals its associated panel's id attribute.

The aria-expanded="false" attribute is present on the button where its associated accordion panel should be closed when the page loads.

12-25

The child .accordion__panel selector is required.

The id attribute equals the value of its associated button's aria-controls attribute.

The data-accordion="panel" attribute is present on the accordion panel for JavaScript purposes.

The aria-labelledby attribute equals the value of its associated buttons's id attribute.

The role="region" attribute is present on the accordion panel for assistive technology.

The granchild .accordion__panel__content selector holds the panel's content. Padding applied to this selector allows a clean open and close transition, without using jQuery.

Semantic Headers

The the .accordion__button selector doesn't have to be a button tag. In fact, header tags in the accordion help describe the architecture of a page. For example, if an accordion group lives below a page's <h1>, the accordion headers could be <h2> tags.

<h2
    class="accordion__button h5"
    id="..."
    data-accordion="button"
    aria-controls="..."
    aria-expanded="false">
        Danaus Plexippus
</h2>
Figure 2

In Figure 2 (line 2) notice the .h5 class. Header utility classes are particularly useful in this example. When a semantic header (e.g. <h1>) needs to be smaller (in visual size) than its natural markup style. You can use header utilities on non-semantic tags (e.g., <button>), that need the appearance of a header.

Open by Default

You may want one of your accordion topics to be open by default (when the page loads), like the following example:

The black swallowtail, American swallowtail, or parsnip swallowtail, is a butterfly found throughout much of North America. It is the state butterfly of Oklahoma and New Jersey.

The cecropia moth is North America's largest native moth. It is a member of the family Saturniidae, or giant silk moths. Females have been documented with a wingspan of five to seven inches or more.

The elephant hawk moth or large elephant hawk moth, is a moth in the family Sphingidae. Its common name is derived from the caterpillar's resemblance to an elephant's trunk. It is most common incentral Europe and is distributed throughout the Palearctic region.

The spicebush swallowtail or green-clouded butterfly, is a common black swallowtail butterfly found in North America. It has two subspecies, Papilio troilus troilus and Papilio troilus ilioneus, the latter found mainly in the Florida peninsula.

<button
    class="accordion__button h5"
    id="acc-button-id"
    data-accordion="button"
    aria-controls="acc-panel-id"
    aria-expanded="true">
        Danaus Plexippus
</button>

<div
    class="accordion__panel show"
    id="acc-panel-id"
    data-accordion="panel"
    aria-labelledby="acc-button-id"
    role="region">
    <div class="accordion__panel__content">
        ...
    </div>
</div>
Figure 3
Line #Details
6

On the .accordion__button selector, set the aria-expanded attribute to "true"

11

On the related .accordion__panel selector, include the class .show.

Related CSS Variables

Further customize Accordions by redefining any of their related CSS variables as shown below.

.accordion {
    --accordion-button-padding-x: var(--spacer-3);
    --accordion-button-padding-y: var(--spacer-3);
    --accordion-panel-padding-x: var(--spacer-3);
    --accordion-panel-padding-y: var(--spacer-3);
    --accordion-active-color: currentColor;
}