Skip to main content

Accordion

Accordion in Storybook
Note: There are deprecated versions of this component. For documentation, see the Accordion (deprecated) page.

Usage​

Overview​

The accordion is a component that allows for progressive display of information. Accordions are useful when you need to deliver large amounts of content within a small space (for example, mobile interface or side panel). They consist of vertically stacked headers, which expand to reveal their associated content. Accordions give users control over how much information they see on the screen at any given time. You might encounter accordions in wizard flows and in mobile solutions, where space is at a premium.

When to use​

  • To disclose content that users can selectively read.
  • When there isn't a lot of vertical space and the content doesn't all need to be displayed at once.
  • To organize related information.

When not to use​

  • For content that is critical to task completion.
  • When you're creating a menu. Instead, consider using the overflow menu component.
  • When you need to nest multiple accordions inside each other. Instead, consider using the tree view component.

Formatting​

Anatomy​

Accordion anatomy

The accordion consists of the following elements:

  1. Header: Title that gives users an overview of the content in that section.
  2. Chevron: Icon that indicates the status of the accordion (expanded or collapsed).
  3. Main content: Associated content that appears when expanding the accordion header. May consist of text or UI elements such as an input field.
  4. Divider: Visual delimiter to distinguish accordion items. It should be visible by default with the option to hide it.

Alignment and placement​

By default, the chevron icon is placed on the right side (at the end) of the header. This allows for the accordion title to align with other content on the page. Icon placement (left or right) must be consistent across all pages within one app.

Accordion alignment and placement

The accordion must fit the whole width of the parent container. To change the width of the accordion, change the container width.

Do match the width of the accordion to the width of the parent container.
Don't make the width of the accordion less than the width of the parent container.

Content​

General writing guidelines​

  • Use sentence case for all aspects of designing Guidewire product interfaces. Don't use title case.
  • Use present tense verbs and active voice in most situations.
  • Use common contractions to lend your copy a more natural and informal tone.
  • Use plain language. Avoid unnecessary jargon and complex language.
  • Keep words and sentences short.

Accordion header​

The accordion header can contain the following:

  • Text (header title and secondary text).
  • Icon (When the chevron is on the right side, you can place an icon before the header title. If the chevron is on the left side, place the icon at the end of the accordion header).
The accordion header can include text, icons, and other non-interactive elements.
Don't add interactive elements, such as buttons, to the accordion header. This violates accessibility.

Each accordion header must have a unique title that clearly and succinctly describes the associated body content. Headers appear in sentence case, except when using proper nouns.

Accordion body​

  • Content in accordions should never scroll horizontally.
  • You may split the contents of an accordion panel into paragraphs and include sub-headers if needed.

Word, character limits​

There is no maximum character or word limit on the header or the main content.

Behaviors​

States​

The accordion component has 2 main states: collapsed and expanded.

  • Collapsed: Default state when the accordion is collapsed and not selected. Closed accordions appear without highlighting and display only the header title.
  • Expanded: Indicates that the user has selected the accordion and expanded it to display content. The chevron icon points downwards to indicate that the accordion has been expanded.

In addition to the collapsed and expanded states, accordions also have interactive states for enabled, disabled, hover, focus, and active.

StateDescription
Enabled stateEnabledDefault state.
Disabled stateDisabledIndicates that the accordion is not interactive but might be at some point. Disabled state is not meant to be accessible so it should not be focused.
Hover stateHoverIndicates a change of styling when the user hovers over the accordion header using a mouse.
Focus stateFocusIndicates that the user has selected (but not expanded) the accordion. The borders of the component are highlighted with our brand color.
Active stateActiveIndicates that the user is clicking or tapping the element.

Interactions​

Mouse​

When a user clicks to open a new accordion item, the items that are already opened remain so. Each interaction requires a user click to prevent disorientation in the UI. Users can collapse and expand the accordion by clicking on the chevron or by clicking anywhere in the header region.

Keyboard​

The accordion header functions as a button. Enter and Space expand and collapse each accordion panel. Navigate through the focusable accordion elements using Tab and Shift+Tab.

Screen reader​

When collapsed, accordion panel content is hidden. The WAI-ARIA state aria-expanded="false" advises users that the panel isn't visible. When expanded, the ARIA attribute changes to 'true' to convey that the content is visible.

Accessibility​

This component has been validated to meet the WCAG 2.2 AA accessibility guidelines in its default, base configuration. This includes ensuring:

  • The contrast ratio of textual elements against their background is above 4.5:1.
  • Non-textual content that needs to convey meaning (like icons and focus indicators) has a contrast ratio of at least 3:1 with its adjacent colors.
  • The item is operable using a keyboard, as well as using a mouse.
  • Content is accessible using screen readers, such as JAWS and VoiceOver.

Accessibility conformance ultimately depends on how this component is implemented and customized. Changes made by the content author can affect accessibility. For details on our shared responsibility model, please review our full Jutro accessibility statement.

Follow the guidance below and also refer to the WAI-ARIA Authoring Practices for Accordions when using this component in your applications:

  • Each accordion header must have a unique title that describes the accordion panel content. This assists blind users, in particular, in that they can navigate through each header and understand the content, without having to expand each panel.
  • Ensure that there are no keyboard traps when adding content to the accordion panel. Users should be able to move to each focusable element within each panel and then move to the next accordion card header.