Skip to contentSkip to footer
Close-up view of a vibrant Monarch caterpillar gracefully navigating a green leaf

Photo: Sara Codair

Accordion

Introduction

The Natura11y accordion allows sections of content to expand and collapse while maintaining accessible semantic structure.

Default Accordion Behavior

Each accordion item consists of:

  • A button that controls expansion
  • A content panel
  • Optional heading markup when the accordion needs semantic heading navigation

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

HTML
<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>...</p>
    </div>
  </div>


</div>
Figure 1
Figure 1 notes
LinesDetails
1

The parent .accordion class is required.

This selector uses JavaScript to group a set of accordion buttons and panels with one another.

3-10

The child .accordion__button selector is required.

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

The data-accordion="button" attribute is used by the JavaScript behavior.

The aria-controls attribute equals the associated panel’s id attribute.

The aria-expanded="false" attribute communicates that the associated panel is closed when the page loads.

12-21

The child .accordion__panel selector is required.

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

The data-accordion="panel" attribute is used by the JavaScript behavior.

The aria-labelledby attribute equals the associated button’s id attribute.

The role="region" attribute identifies the panel as a region for assistive technology.

The .accordion__panel__content selector holds the panel content. Its padding and opacity animate separately from the panel’s grid transition.

Semantic Headers

Accordion buttons can be wrapped in heading elements to support screen reader heading navigation. This follows the W3C APG accordion pattern. If an accordion group lives below a page’s <h2>, wrap each button in an <h3>.

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

HTML
<h3 data-accordion="heading">


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


</h3>


<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">
    ...
  </div>
</div>
Figure 2
Figure 2 notes
LinesDetails
1

The data-accordion="heading" attribute is required on the heading wrapper. It resets the heading’s visual styles so only the semantic heading role is preserved.

3-10

The .accordion__button markup is identical to the default pattern in Figure 1.

Open by Default

You may want one accordion topic to be open when the page loads.

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

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


<div
  class="accordion__panel shown"
  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...</p>
  </div>
</div>
Figure 3
Figure 3 notes
LinesDetails
6

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

11

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

Active Text Underline

Add a <span> with the .text class inside the button to underline the label when the panel is open. This gives users a second visual signal beyond color alone.

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

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

Collapse

Tab