Accordion

Vertically-stacked list that allows users to expand and collapse additional content

# Overview

# Default (Medium)

Section borders expand to full width of container.

# Compact (Small)

Reduced spacing around title and content body. Also, smaller font sizes resulting in overall denser display of content.

# Border Aligned

Border aligns to the title text and expand/collapse icon.

# Accessibility

To ensure that usage of this component complies with accessibility guidelines:

  • Provide descriptive label for accordion header
  • Be aware that embedding lengthy content in an accordion can be disorienting. When the accordion header expands, it can give the appearance of moving to another page

This component has compliance with WCAG guidelines by:

  • Providing keyboard interactions to:
    • Expand and collapse accordion headers
    • Navigate and reverse navigate through the accordion headers
  • Generating ARIA tags for accessibility, specifically aria-controls, aria-expanded, and aria-hidden

# Guidelines

# Use When

  • Providing users more content within the same layout
  • Displaying content that is directly related, or supplemental, to the main subject of the page
  • Designing with limited vertical space and there is enough content to condense

# Don't Use When

  • Linking a title to another page. Instead, use Links
  • Designing with sparse content. Instead, use Lists or Paragraphs
  • Content is lengthy. Instead, use Tabs

# The Basics

  • Use on either light or dark backgrounds. Background color is provided for both
  • Content within accordions can include text, photos, graphics, or other components (i.e. links, buttons, tables)

# Content

  • Order the accordion titles by priority and importance
  • Keep titles short to avoid wrapping at smaller viewports
  • Use sentence case for titles
  • Use short titles for accordion labels to avoid wrapping
  • Always include a title, icon, and subsequent content for each section. All are required

# Anatomy

  • Position interactive elements (i.e. Select, Button, Link) within the container far enough from the title area to avoid accidental collapsing

# Behavior

  • Entire title area is clickable, including icon and background
  • Never nest accordions within themselves

# Show and Hide

  • Revealing the first accordion section is recommended
  • Other accordion sections are all hidden by default, however it is possible to specify that:
    • All accordion sections are revealed when page is displayed
    • A specific accordion section is revealed with remaining accordion section closed
  • Sections do not automatically collapse when another is expanded

# Do / Don't

Image showing proper accordion usage
Do present content in a single accordion.
Image showing nested accordions
Don't nest accordions.

Image showing short and succinct accordion titles
Do keep titles short and concise.
Image showing a too long accordion title wrapped to many lines
Don't create labels so lengthy that they wrap to a second line.

# Responsiveness

  • Accordion style can change variant based on breakpoint. Example: Default at MD/LG can change to Compact and Border-Aligned at XS/SM
  • Switching between the Tab component and the Accordion component is not supported in Cedar components library
  • Do not replace the Accordion component with the Tab component at different breakpoints

# API

# Props

id

name

string

type

N/A

default

Unique id required.

Deprecated in v3.0.0. Instead, use 'label' slot.

label

name

string

type

N/A

default

Sets the readable text on the CdrAccordion button. Deprecated. Use label slot.

opened

name

boolean

type

false

default

Toggle to open/close the accordion.

compact

name

boolean

type

false

default

Sets the compact style.

borderAligned

name

boolean

type

false

default

Sets the border-aligned style.

# Slots

Find more information about using Slots in the article Getting Started as a Developer.

label

name

Sets the readable text on the CdrAccordion button. Use this slot instead of label prop.

default

name

Slot for the CdrAccordion content.

# Events

accordion-toggle

name

event

arguments

$emit event fired on CdrAccordion toggle.

# Usage

CdrAccordion emits an event when its button is clicked. Use an event listener to toggle the value of the opened prop to open or close the accordion.

<template>
  <cdr-accordion
    id="item"
    :compact="true"
    :opened="opened"
    @accordion-toggle="opened = !opened"
  >
    <template slot="label">
      Click me to show content!
    </template>
      This content is revealed when the accordion is opened.
  </cdr-accordion>
</template>

<script>
export default {
  ...
  data() {
    return {
      opened: false
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

CdrAccordion can also be wired up into groups if, for instance, you wanted to close the other accordions when one is opened.

<cdr-accordion
  v-for="(item, index) in grouped"
  :id="item.id"
  :border-aligned="true"
  :opened="item.opened"
  :key="item.id"
  @accordion-toggle="updateGroup(index)"
>
  <template slot="label">
    {{ item.label }}
  </template>
  {{ item.content }}
</cdr-accordion>

<script>
export default {
  ...
  data() {
    return {
      grouped: [
        {
          label: 'These are border-aligned',
          content: 'These accordions will only allow one open at a time.',
          opened: false,
          id: 'linked1',
        },
        {
          label: 'And they are also linked',
          content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. ',
          opened: false,
          id: 'linked2',
        },
        {
          label: 'To close others when one is opened',
          content: 'These accordions will only allow one open at a time.',
          opened: false,
          id: 'linked3',
        },
      ],
    }
  },
  methods: {
    updateGroup(index) {
      const { opened } = this.grouped[index];
      if (opened) {
        // closing opened accordion
        this.grouped[index].opened = false;
      } else {
        // open closed accordion. close all others.
        for (let i = 0; i < this.grouped.length; i += 1) {
          this.grouped[i].opened = index === i;
        }
      }
    },
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57