Accordion

Group collapsible sections behind headings people can open and close, one or several at a time.

When to use

Use an accordion when your content would benefit from collapsing sections of content under their headings.

For a single section, use the details pattern.

How to use

Write a heading for each section that says what it opens. When everything is closed, the headings are all people have to go on, so make them specific.

Decide whether people open one section at a time or several at once. One at a time keeps the page short. Several at once helps when people compare sections without having to remember what they read in a recently closed section.

Setup

Wrap a group of details in pennlibs-accordion.

Space the accordion items with the flex and gap utilities on the accordion, like pl-flex pl-flex-col pl-gap-m.

The component adds keyboard navigation, so people can move between headings with the arrow keys and jump to the first or last with Home or End.

<div class="pl-reset pl-typeset pl-margin-l">
  <pennlibs-accordion class="pl-flex pl-flex-col pl-gap-m">
    <details class="pl-details">
      <summary class="pl-details__summary"><h3>Scope and Contents</h3></summary>
      <div class="pl-details__content">
        <p>The collection documents the professional and personal life of the subject, including correspondence, photographs, and concert programs.</p>
      </div>
    </details>
    <details class="pl-details">
      <summary class="pl-details__summary"><h3>Biographical / Historical</h3></summary>
      <div class="pl-details__content">
        <p>Born in Philadelphia, the subject rose to international prominence and toured widely throughout Europe, South America, and Asia.</p>
      </div>
    </details>
    <details class="pl-details">
      <summary class="pl-details__summary"><h3>Arrangement</h3></summary>
      <div class="pl-details__content">
        <p>The papers are arranged in five series: Correspondence, Writings, Photographs, Programs, and Memorabilia.</p>
      </div>
    </details>
  </pennlibs-accordion>
</div>

Expand all

To let people open or close every section at once, put a button inside the accordion with data-pl-accordion-toggle. Add data-pl-expand-label and data-pl-collapse-label to swap its text as the state changes.

By default the data-pl-accordion-toggle button acts on the accordion it sits inside. To control one from elsewhere on the page, give the accordion an id and put it in the value, like data-pl-accordion-toggle="series".

<div class="pl-reset pl-typeset pl-margin-l">
  <pennlibs-accordion class="pl-flex pl-flex-col pl-gap-m">
    <div>
      <button type="button" class="pl-button" data-pl-accordion-toggle
        data-pl-expand-label="Expand all" data-pl-collapse-label="Collapse all">Expand all</button>
    </div>
    <details class="pl-details">
      <summary class="pl-details__summary"><h3>Scope and Contents</h3></summary>
      <div class="pl-details__content">
        <p>The collection documents the professional and personal life of the subject.</p>
      </div>
    </details>
    <details class="pl-details">
      <summary class="pl-details__summary"><h3>Arrangement</h3></summary>
      <div class="pl-details__content">
        <p>The papers are arranged in five series.</p>
      </div>
    </details>
  </pennlibs-accordion>
</div>

Nesting

Put an accordion inside a section to group content by levels. Each accordion controls only its own level.

To open a level and everything nested inside it, add data-pl-accordion-toggle-deep to the data-pl-accordion-toggle button. Give it a number, like data-pl-accordion-toggle-deep="1", to reach only that many levels down.

<div class="pl-reset pl-typeset pl-margin-l">
  <pennlibs-accordion class="pl-flex pl-flex-col pl-gap-m">
    <div>
      <button type="button" class="pl-button" data-pl-accordion-toggle data-pl-accordion-toggle-deep
        data-pl-expand-label="Expand all" data-pl-collapse-label="Collapse all">Expand all</button>
    </div>
    <details class="pl-details">
      <summary class="pl-details__summary"><h3>Series I. Correspondence</h3></summary>
      <div class="pl-details__content">
        <p>Letters to and from the subject, arranged chronologically.</p>
        <pennlibs-accordion class="pl-flex pl-flex-col pl-gap-m">
          <details class="pl-details">
            <summary class="pl-details__summary"><h4>Subseries A. Incoming</h4></summary>
            <div class="pl-details__content">
              <p>Letters received, 1924 to 1965.</p>
            </div>
          </details>
          <details class="pl-details">
            <summary class="pl-details__summary"><h4>Subseries B. Outgoing</h4></summary>
            <div class="pl-details__content">
              <p>Copies of letters sent, 1924 to 1965.</p>
            </div>
          </details>
        </pennlibs-accordion>
      </div>
    </details>
    <details class="pl-details">
      <summary class="pl-details__summary"><h3>Series II. Writings</h3></summary>
      <div class="pl-details__content">
        <p>Drafts, speeches, and published articles.</p>
      </div>
    </details>
  </pennlibs-accordion>
</div>

Attributes

Attribute	Description	Type	Default
`single`	When set, only one panel can be open at a time, so opening one closes the others, like a classic accordion.	`boolean`	`false`

Slots

Slot	Description
	One or more details items, each styled with the pl-details classes.

Expand button attributes

Attribute	Description
`data-pl-accordion-toggle`	Marks an element as a toggle-all control. With no value it controls the closest accordion. Set the value to an accordion's `id` to control one from elsewhere on the page.
`data-pl-accordion-toggle-deep`	Also opens nested accordions. A bare attribute reaches every level. A number, like `data-pl-accordion-toggle-deep="2"`, reaches that many levels down.
`data-pl-expand-label`, `data-pl-collapse-label`	Text the control shows when the sections are closed and when they are open.

Accordion (WAI-ARIA Authoring Practices)