Accordion
An accordion lets users show and hide sections of related content.
import { ... } from '@ag.ds-next/react/accordion';<Accordion> <AccordionItem title="Accordion 1"> <AccordionItemContent> <Text as="p">Here is the accordion content.</Text> </AccordionItemContent> </AccordionItem> <AccordionItem title="Accordion 2"> <AccordionItemContent> <Text as="p">Here is the accordion content.</Text> </AccordionItemContent> </AccordionItem> <AccordionItem title="Accordion 3"> <AccordionItemContent> <Text as="p">Here is the accordion content.</Text> </AccordionItemContent> </AccordionItem> </Accordion>
Users can open or close an accordion to decide on the content they see.
An accordion can save space when space is limited. It can also help a user quickly scan page contents. Users can skim-read the list of headings in the accordion and get an overview of the content.
Generally speaking, use accordions sparingly.
Do
- use accordions for content that is only relevant to some users
- try simplifying or splitting long page content into more pages before using accordions
- use up to 10 accordions in a group
- use accordions to help users skim-read a list and get an overview of content. For example, a step-by-step process
- use accordions if there’s evidence they help users and the benefits outweigh the negative impact on usability.
Don’t
- use accordions for content that is relevant to all users
- use an accordion if body content is short. Use a well-formatted paragraph or list instead
- use accordions if there’s evidence they don’t help the user, or content without accordions tests well.
Accordion
The default state for an accordion is a closed state.
Sections and accordions that start closed give the user an overview of all content.
You can set sections to start and stay open, if the user leaves then returns to the page.
<Accordion> <AccordionItem title="Accordion title"> <AccordionItemContent> <Text as="p">Here is the accordion content.</Text> </AccordionItemContent> </AccordionItem> </Accordion>
Accordion group
It’s common for more than one accordion to appear together.
You can stack up to 10 accordions vertically in a group. If you need to use more than 10, redesign the content to reduce the number instead.
Grouped accordions are single action accordions. They don’t influence each other – if one opens, another doesn’t close.
Users can choose what content they want to see.
<Accordion> <AccordionItem title="Accordion 1"> <AccordionItemContent> <Prose> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce a libero vel dolor sollicitudin pretium quis quis mi. Fusce sapien mi, efficitur sit amet ex et, bibendum efficitur odio. Ut nec gravida metus, nec suscipit nulla. Donec est nulla, dictum sed ultricies congue, suscipit at velit. Integer ut leo lectus. Nullam volutpat ex quis imperdiet scelerisque. Etiam ultrices et nisi eget pulvinar. Cras ultrices lectus ut nisl gravida, eu rutrum sem luctus. Praesent vulputate eu dolor commodo tempor. Sed nec lorem consectetur, maximus justo at, tincidunt quam. Suspendisse pellentesque accumsan accumsan. Cras in odio leo. Nam pharetra, lorem eget aliquam gravida, felis ex tempor sapien, a ornare leo nulla eget magna. Quisque tempus ipsum eu elit bibendum, nec bibendum ligula posuere. Nam porttitor est eros, ac maximus nisl euismod nec. </p> </Prose> </AccordionItemContent> </AccordionItem> <AccordionItem title="Accordion 2"> <AccordionItemContent> <Prose> <p> Curabitur urna erat, ornare in nulla vitae, tempor porttitor dolor. Nam luctus fermentum tellus, vitae maximus turpis viverra eget. Phasellus hendrerit tortor eu mauris ultricies congue. Suspendisse cursus, purus quis viverra pharetra, purus quam hendrerit magna, condimentum cursus massa nisi ut est. Mauris in tristique augue. Phasellus tellus ante, fermentum eget fringilla eget, tempor nec nunc. Ut nec dui vitae ex dignissim tempus ac et ante. Donec imperdiet suscipit leo. Suspendisse mattis quis nisl id mattis. Sed dictum tempus nibh, quis feugiat magna efficitur in. Sed vulputate et dui eu malesuada. </p> </Prose> </AccordionItemContent> </AccordionItem> <AccordionItem title="Accordion 3"> <AccordionItemContent> <Prose> <p> Curabitur urna erat, ornare in nulla vitae, tempor porttitor dolor. Nam luctus fermentum tellus, vitae maximus turpis viverra eget. Phasellus hendrerit tortor eu mauris ultricies congue. Suspendisse cursus, purus quis viverra pharetra, purus quam hendrerit magna, condimentum cursus massa nisi ut est. Mauris in tristique augue. Phasellus tellus ante, fermentum eget fringilla eget, tempor nec nunc. Ut nec dui vitae ex dignissim tempus ac et ante. Donec imperdiet suscipit leo. Suspendisse mattis quis nisl id mattis. Sed dictum tempus nibh, quis feugiat magna efficitur in. Sed vulputate et dui eu malesuada. </p> </Prose> </AccordionItemContent> </AccordionItem> </Accordion>
Indented accordion
The indent prop of the the accordion adds padding to the left and right of the title and content. This separates it from the edge of the container and can also help to show hierarchy in complex layouts.
<Accordion indent> <AccordionItem title="Accordion 1"> <AccordionItemContent> <Prose> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce a libero vel dolor sollicitudin pretium quis quis mi. Fusce sapien mi, efficitur sit amet ex et, bibendum efficitur odio. Ut nec gravida metus, nec suscipit nulla. Donec est nulla, dictum sed ultricies congue, suscipit at velit. Integer ut leo lectus. Nullam volutpat ex quis imperdiet scelerisque. Etiam ultrices et nisi eget pulvinar. Cras ultrices lectus ut nisl gravida, eu rutrum sem luctus. Praesent vulputate eu dolor commodo tempor. Sed nec lorem consectetur, maximus justo at, tincidunt quam. Suspendisse pellentesque accumsan accumsan. Cras in odio leo. Nam pharetra, lorem eget aliquam gravida, felis ex tempor sapien, a ornare leo nulla eget magna. Quisque tempus ipsum eu elit bibendum, nec bibendum ligula posuere. Nam porttitor est eros, ac maximus nisl euismod nec. </p> </Prose> </AccordionItemContent> </AccordionItem> <AccordionItem title="Accordion 2"> <AccordionItemContent> <Prose> <p> Curabitur urna erat, ornare in nulla vitae, tempor porttitor dolor. Nam luctus fermentum tellus, vitae maximus turpis viverra eget. Phasellus hendrerit tortor eu mauris ultricies congue. Suspendisse cursus, purus quis viverra pharetra, purus quam hendrerit magna, condimentum cursus massa nisi ut est. Mauris in tristique augue. Phasellus tellus ante, fermentum eget fringilla eget, tempor nec nunc. Ut nec dui vitae ex dignissim tempus ac et ante. Donec imperdiet suscipit leo. Suspendisse mattis quis nisl id mattis. Sed dictum tempus nibh, quis feugiat magna efficitur in. Sed vulputate et dui eu malesuada. </p> </Prose> </AccordionItemContent> </AccordionItem> <AccordionItem title="Accordion 3"> <AccordionItemContent> <Prose> <p> Curabitur urna erat, ornare in nulla vitae, tempor porttitor dolor. Nam luctus fermentum tellus, vitae maximus turpis viverra eget. Phasellus hendrerit tortor eu mauris ultricies congue. Suspendisse cursus, purus quis viverra pharetra, purus quam hendrerit magna, condimentum cursus massa nisi ut est. Mauris in tristique augue. Phasellus tellus ante, fermentum eget fringilla eget, tempor nec nunc. Ut nec dui vitae ex dignissim tempus ac et ante. Donec imperdiet suscipit leo. Suspendisse mattis quis nisl id mattis. Sed dictum tempus nibh, quis feugiat magna efficitur in. Sed vulputate et dui eu malesuada. </p> </Prose> </AccordionItemContent> </AccordionItem> </Accordion>
Accordion edge-to-edge image
An accordion can open to reveal an image the full width of the panel.
This text is wrapped in the AccordionContent component.
<Accordion> <AccordionItem title="Edge-to-edge image"> <img alt="Placeholder" src="/img/placeholder/600X260.png" width="100%" /> <AccordionItemContent> <Text as="p"> In this example, we remove the default padding from the AccordionItem, in order to achieve the edge-to-edge image above. This Text is wrapped in the AccordionItemContent component. </Text> </AccordionItemContent> </AccordionItem> </Accordion>
Backgrounds
The background of the AccordionItem must pair with the background it is being placed on. For example, if AccordionItem is placed on a bodyAlt background, please set the background prop to 'bodyAlt'.
<Stack background="bodyAlt" padding={3} gap={1}> <Text>An area with `bodyAlt` background</Text> <Accordion> <AccordionItem title="Accordion title" background="bodyAlt"> <AccordionItemContent> <Text as="p"> This AccordionItem has background set to ‘bodyAlt’, so it sits well inside of this area. </Text> </AccordionItemContent> </AccordionItem> </Accordion> </Stack>
Colour
AgDS foreground components respond to the background colour of their parent container. When placed on a dark palette background, the dark palette variant of the component is displayed. When placed on a light palette background the light palette variant is displayed.
This logic ensures sufficient contrast between foreground and background elements is maintained to meet WCAG 2.1 AA, 4:5:1 contrast ratio for text (WCAG 1.4.3) and 3:1 for graphic elements that convey information (WCAG 1.4.11).
This component has a 'bodyAlt' variant. Components with a 'bodyAlt' variant utiliseshadeAlt to highlight interface components and content that sit on 'bodyAlt' background. shadeAlt is also used to fill interactive components, ensuring sufficient contrast is maintained for hover states.
Light palette
<Box background="body" paddingX={{ xs: 0.75, md: 1.5 }} paddingY={1.5}> <> <Box padding={1.5}> <Accordion> <AccordionItem background="body" isInitiallyOpen title="Accordion: on light body background" > <AccordionItemContent> <Stack gap={1}> <Text as="p">Here is the accordion content.</Text> <TextLink href="#">Text link</TextLink> </Stack> </AccordionItemContent> </AccordionItem> </Accordion> </Box> <Box background="bodyAlt" padding={1.5}> <Accordion> <AccordionItem background="bodyAlt" isInitiallyOpen title="Accordion: on light bodyAlt background" > <AccordionItemContent> <Stack gap={1}> <Text as="p">Here is the accordion content.</Text> <TextLink href="#">Text link</TextLink> </Stack> </AccordionItemContent> </AccordionItem> </Accordion> </Box> </> </Box>
Dark palette
<Box background="body" paddingX={{ xs: 0.75, md: 1.5 }} paddingY={1.5} palette="dark"> <> <Box padding={1.5}> <Accordion> <AccordionItem background="body" isInitiallyOpen title="Accordion: on dark body background" > <AccordionItemContent> <Stack gap={1}> <Text as="p">Here is the accordion content.</Text> <TextLink href="#">Text link</TextLink> </Stack> </AccordionItemContent> </AccordionItem> </Accordion> </Box> <Box background="bodyAlt" padding={1.5}> <Accordion> <AccordionItem background="bodyAlt" isInitiallyOpen title="Accordion: on dark bodyAlt background" > <AccordionItemContent> <Stack gap={1}> <Text as="p">Here is the accordion content.</Text> <TextLink href="#">Text link</TextLink> </Stack> </AccordionItemContent> </AccordionItem> </Accordion> </Box> </> </Box>