Helsinki Design System
Helsinki Design System
Getting started
Tutorials
Guidelines
Visual assets
Design tokens
Components
OverviewAccordionPrinciplesAccessibilityUsage & variationsDemos & APIButtonCardCheckboxDate inputDialogDropdownFieldsetFooterIconKorosLoading spinnerLogoNavigationNotificationNumber inputPassword inputPhone inputRadio buttonSearch inputSelection groupStatus labelTabsTagText fieldsTime inputToggle buttonTooltip
Patterns
About
Contributing
Resources

Accordion

StableAccessible

Accordions can be used to hide and reveal information. When used correctly, they are a good way to make higher amount of information easier to digest for the user.

Principles

  • Use accordions to allow the user to quickly glance the information and then choose to open sections that are interesting to them.
  • Accordions must be given a header that describes the accordion content. This header also acts as the label for the expand button. The header level can be chosen depending on the structure of the page.
  • Do not put essential or must-read information inside accordions. If the user is expected to open all of the accordions while using the service, then it is likely that the information should not be inside accordions.
    • Accordions work well when the user usually needs only part of the information. You may also consider placing parts of lower importance inside accordions while the most important parts are always visible.
  • Do not use accordions to create step-by-step forms. You must not expect that the user opens all accordions in a specific order.
  • Accordions should initially be closed when the page is loaded.
  • Expanding or closing the accordion should only affect to the related accordion area. You also should not auto-close or auto-open accordions.

Accessibility

  • Use HDS provided accordion elements when creating custom accordions. These elements pass accessibility testing.
  • When creating custom accordions, make sure that the expanded accordion area directly follows the accordion button in the DOM tree.
    • If you must place the accordion area somewhere else, use aria-owns attribute to indicate the relationship. However, be aware that this attribute does not necessarily work with all screen readers.
  • Make sure that the keyboard user can navigate out of the accordion area without closing the accordion. See WCAG 2.1.2 No Keyboard Trap guideline for more information.

Usage & variations

Default accordion

Basic HDS Accordions provide two different visuals to choose from. These implementations are easy to take into use if you do not need any special functionality or styling.

This style is visually less distracting and it works well when there are multiple accordions one below another or nearby.

How to publish data?

React code example:

<Accordion
heading="How to publish data?"
style={{ maxWidth: '360px' }}
>
To publish your data, open your profile settings and click buttton 'Publish'.
</Accordion>

Accordion with a card

You can also use HDS Cards as a container for your Accordions. Cards offer the same customizability options as default HDS Cards. To learn more about Cards and their customization, refer to HDS Card documentation.

If you have multiple accordions one below another or many accordions in the same view, consider using the visually more light default styling variant instead of this one.

How to publish data?

React code example:

<Accordion
card
border
heading="How to publish data?"
style={{ maxWidth: '360px'}}
>
To publish your data, open your profile settings and click buttton 'Publish'.
</Accordion>

Accordion with custom styles

You can easily customize HDS Accordions by giving them a theme prop.

How to publish data?
How to publish data?

React code example:

<Accordion
card
border
heading="How to publish data?"
style={{ maxWidth: '360px'}}
theme={{
'--background-color': 'var(--color-white)',
'--border-color': 'var(--color-brick)',
'--padding-horizontal': 'var(--spacing-m)',
'--padding-vertical': 'var(--spacing-m)',
'--header-font-color': 'var(--color-black-90)',
'--header-font-size': 'var(--fontsize-heading-l)',
'--header-line-height': 'var(--lineheight-l)',
'--button-size': '28px',
'--button-border-color-hover': 'var(--color-coat-of-arms)',
'--content-font-color': 'var(--color-black-90)',
'--content-font-size': 'var(--fontsize-body-m)',
'--content-line-height': 'var(--lineheight-l)',
}}
>
To publish your data, open your profile settings and click buttton 'Publish'.
</Accordion>
<Accordion
card
heading="How to publish data?"
style={{ maxWidth: '360px', marginTop: 'var(--spacing-s)'}}
theme={{
'--background-color': 'var(--color-bus)',
'--padding-horizontal': 'var(--spacing-m)',
'--padding-vertical': 'var(--spacing-m)',
'--header-font-color': 'var(--color-white)',
'--header-font-size': 'var(--fontsize-heading-s)',
'--header-line-height': 'var(--lineheight-s)',
'--button-size': '28px',
'--button-border-color-hover': 'var(--color-white)',
'--content-font-color': 'var(--color-white)',
'--content-font-size': 'var(--fontsize-body-m)',
'--content-line-height': 'var(--lineheight-l)',
}}
>
To publish your data, open your profile settings and click buttton 'Publish'.
</Accordion>

Custom accordion

If the basic accordion components do not fit for your needs, you can build a custom accordion by using HDS provided accordion elements.

React code example:

import { Accordion, useAccordion, Button, Card } from 'hds-react';
const CustomAccordion = () => {
// Handle accordion state with useAccordion hook
const { isOpen, buttonProps, contentProps } = useAccordion({ initiallyOpen: false });
// Change icon based on accordion open state
const icon = isOpen ? <IconAngleUp aria-hidden /> : <IconAngleDown aria-hidden />;
return (
<>
<Button iconLeft={icon} {...buttonProps}>Advanced filters</Button>
<Card border aria-label="Advanced filters" {...contentProps}>
Accordion content
</Card>
</>
);
}

Demos & API

Core

Not included in hds-core!

React

Accordion in hds-react

Accordion API