Stable

Accordion

Accordions are useful for simplifying overwhelming pages or progressively disclosing steps of a process. Be conscious that accordions require user interaction to see information and think about whether the cost of that is worthwhile. If an accordion is hiding only a small amount of information then perhaps an accordion is unnecessary. Consider accordions as an accompanyment to the key content of the page, allowing the user to focus on the important content outside of the accordion, whilst having easy access to complimentary content within the accordions.

GitHub, opens in a new tab·Storybook, opens in a new tab·Playroom, opens in a new tab·Figma, opens in a new tab

Installation

bash

npm install @nib-components/accordion

Note: You will also need to install the peerDependencies @nib/icons and @nib-components/theme.

Usage

jsx

import Accordion from '@nib-components/accordion';

Note: If you are using this component within a React Server Component (like the NextJS 13 App Router), it is suggested to import Accordion and AccordionItem individually.

jsx

import Accordion, {AccordionItem} from '@nib-components/accordion';

jsx

<Accordion>
  <AccordionItem title="Diam parturient" icon={StethoscopeSystemIcon}>
    Diam parturient a a lorem augue montes
  </AccordionItem>
  <AccordionItem title="Parturient habitasse" icon={YogaSystemIcon}>
    Parturient habitasse tincidunt porttitor
  </AccordionItem>
</Accordion>

Interactive demo

jsx

<Accordion borderTop={false} borderBottom multiExpanded={false}>
  <Accordion.Item subtitle="What they do and how many we get" title="Fun facts about teeth">
    <p>The human teeth are used to mechanically break down items of food by cutting and crushing them in preparation for swallowing and digesting.</p>
    <SecondaryButton>Teeth are awesome</SecondaryButton>
  </Accordion.Item>
  <Accordion.Item subtitle="Organ function and location" title="Heart info">
    <p>
      The heart is a muscular organ in humans and other animals, which pumps blood through the blood vessels of the circulatory system. Blood provides the body with oxygen and nutrients, as well as
      assists in the removal of metabolic wastes. In humans, the heart is located between the lungs, in the middle compartment of the chest.
    </p>
  </Accordion.Item>
  <Accordion.Item subtitle="Anatomy - gross and microscopic" title="The human body">
    <p>
      Human anatomy – scientific study of the morphology of the adult human. It is subdivided into gross anatomy and microscopic anatomy. Gross anatomy (also called topographical anatomy, regional
      anatomy, or anthropotomy) is the study of anatomical structures that can be seen by unaided vision.
    </p>
  </Accordion.Item>
</Accordion>

<Accordion borderTop={false} borderBottom multiExpanded={false}>
  <Accordion.Item subtitle="What they do and how many we get" title="Fun facts about teeth">
    <p>The human teeth are used to mechanically break down items of food by cutting and crushing them in preparation for swallowing and digesting.</p>
    <SecondaryButton>Teeth are awesome</SecondaryButton>
  </Accordion.Item>
  <Accordion.Item subtitle="Organ function and location" title="Heart info">
    <p>
      The heart is a muscular organ in humans and other animals, which pumps blood through the blood vessels of the circulatory system. Blood provides the body with oxygen and nutrients, as well as
      assists in the removal of metabolic wastes. In humans, the heart is located between the lungs, in the middle compartment of the chest.
    </p>
  </Accordion.Item>
  <Accordion.Item subtitle="Anatomy - gross and microscopic" title="The human body">
    <p>
      Human anatomy – scientific study of the morphology of the adult human. It is subdivided into gross anatomy and microscopic anatomy. Gross anatomy (also called topographical anatomy, regional
      anatomy, or anthropotomy) is the study of anatomical structures that can be seen by unaided vision.
    </p>
  </Accordion.Item>
</Accordion>

Props

Accordion

Prop	Type	Default	Description
`borderTop`	boolean	`false`	Whether there is a border at the top of the accordion.
`borderBottom`	boolean	`true`	Whether there is a border at the bottom of the accordion. Unlike `borderTop` this prop is passed down to `Accordion.Item` to override its usual bottom border.
`multiExpanded`	boolean	`false`	Allow more than one `Accordion.Item` to be open at a time.
`expandedIndex`	number		Initially open an accordion item.
`children`	node		A set of `Accordion.Item`s.

Accordion.Item

Prop	Type	Default	Description
`title` (required)	string		The accordion item title.
`titleComponent`	string	`h4`	THe HTML element for the `Accordion.Item` title.
`subtitle`	string		The accordion item subtitle.
`icon`	node		A system icon to render for the `Accordion.Item`
`onExpand`	function		Callback funtion that gets called on expand.
`onCollapse`	function		Callback funtion that gets called on collapse.
`onBeforeExpand`	function		Callback funtion that gets called before expanding.
`onBeforeCollapse`	function		Callback funtion that gets called before collapsing.
`children`	node		The accordion content.
`contentPadding`	number		Padding of the AccordionItem content.
`hideItemBorder`	boolean		Toggle the AccordionItem content border-bottom

Subtitles

Each accordion item has the option of including a descriptive label subtitle. Subtitles help when further context is required before accordion content is disclosed. Keep subtitles short and succint.

Icons

Each accordion item also has the option of including a system icon. Only system icons should be used with accordions, and their size is fixed at sm. Please do not use Graphic Icons as they are not designed to be used at small sizes.

If a suitable system icon cannot be found, you can request an icon be added to the library using our feedback form, or not include icons in your accordion.

jsx

<Accordion>
  <Accordion.Item title="Get moving" icon={BasketballSystemIcon}>
    <p>👋</p>
  </Accordion.Item>
  <Accordion.Item title="Secure" icon={FingerprintSystemIcon}>
    <p>👋</p>
  </Accordion.Item>
</Accordion>

<Accordion>
  <Accordion.Item title="Get moving" icon={BasketballSystemIcon}>
    <p>👋</p>
  </Accordion.Item>
  <Accordion.Item title="Secure" icon={FingerprintSystemIcon}>
    <p>👋</p>
  </Accordion.Item>
</Accordion>

Considerations

An accordion can help breakdown long content into discreet sections helping consumption and comprehension.

The accordion component may not be fit for purpose if that means hiding important information from the user or to simply to make a page smaller or hide required content for SEO purposes.

Ensuring semantic heading hierarchy

A logical heading hierarchy is extremely important for accessibility, specifically for screen reader users who navigate by headings. Therefore it is important that the correct level of heading be used for the accordion title. The titleComponent prop should be used to set the correct heading level for the title to ensure the correct heading hierarchy is maintained.

jsx

<main>
  <Heading size={1}>Page title</Heading>
  <Accordion>
    <Accordion.Item title="First item" titleComponent="h2">
      <p>Lorem ipsum.</p>
    </Accordion.Item>
    <Accordion.Item title="Last item" titleComponent="h2">
      <p>Dolor sit amet.</p>
    </Accordion.Item>
  </Accordion>

  <section>
    <Heading size={2}>Sub section</Heading>
    <Accordion>
      <Accordion.Item title="First item" titleComponent="h3">
        <p>Lorem ipsum.</p>
      </Accordion.Item>
      <Accordion.Item title="Last item" titleComponent="h3">
        <p>Dolor sit amet.</p>
      </Accordion.Item>
    </Accordion>
  </section>
</main>

SEO and page ranking

If the primary purpose for specific accordion/s content is to rank in Google this is NOT recommended, nor fit for purpose of the SEO goal.

Avoid using an accordion to keyword stuff or hide SEO specific content that may not be relevant to the rendered content and overall user experience.

If the content is supportive to the overall SEO strategy, and the primary purpose is to assist and improve the user experience this tactic is valid.

Prior to version 5.0.3 the contents of the accordion would not be crawlable by SEO robots. New versions will have better SEO performance but still refer to earlier points for correct accordion usage.

Edit this page

Accordion

Installation

Usage

Interactive demo

Props

Accordion

Accordion.Item

Subtitles

Accordion item oneWith a subtitle

Accordion item two

Icons

Considerations

Ensuring semantic heading hierarchy

SEO and page ranking