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




  • Use accordions to allow the user to quickly glance at 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.
    • The headingLevel given to the Accordion should be higher than the header in the page content preceeding it (if there is one). For example if the Accordion is nested inside content with a header h2 then the headingLevel for the Accordion should be 3.
  • 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.
  • By default, accordions include a close button that is visible at the bottom of an expanded accordion. This is meant to allow the user to close the accordion quickly if needed.
    • The close button can be hidden with the closeButton property. While it is recommended to include the button, it can be left out in accordions with very little content.
  • Do not use accordions to create step-by-step forms. You must not expect that the user opens all accordions in a specific order.
  • It is recommended to have accordions closed when the page is loaded.
    • If you need to have the accordion initially open, you can use the initiallyOpen property to achieve this.
    • Having an accordion initially open could be needed e.g. when the user returns to a page and you want to retain accordions' states.
    • Accordions should initially be closed when the page is loaded.
  • Expanding or closing the accordion should only affect the related accordion area. You also should not auto-close or auto-open accordions.



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.

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. If stacking Accordions in a Card with borders, use the same sized variant for all and remove the top borders after the 1st Accordion as in stacked Accordions example.

With the close button hidden

In accordions that have very little content the close button does not offer much utility to the user. In these cases the button can be hidden with the closeButton property.

Accordion size variants

HDS Accordion includes three (3) size variants; small, default, and large. You can use different sizes depending on the screen size or use case. Use the size property to alter the size.

Accordions, heading elements and headingLevel-property

When using multiple Accordions as a group with a shared header or the page content has a header preceding the Accordion(s), keep in mind the basics of using the header elements, h1 being the most important header on the page down to h6 being the least important and give the Accordion the proper headingLevel according to its position.

Header element for the content in which the following Accordions are nested in. (Here this is an h5 element)

Custom accordion

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