## Usage

The `<Accordion />` component allows a user to gain a quick overview of information via the header, which they can click to expand or collapse the additional details beneath.

```tsx live
<Accordion title="Accordion title">Accordion details</Accordion>
```

## Accessibility

It is important to consider the heading structure of your whole page when adding an `<Accordion />` or `<AccordionGroup />`. The heading in your accordion should fall logically within the page's heading hierarchy to help assistive technology users navigate the page. By default, the `titleHeadingLevel` prop is set to `2`, rendering a `<h2>` as the HTML element for the heading with the style of a `<h6>`. You can adjust this level via the `titleHeadingLevel` prop by setting it to 2, 3, 4, 5 or 6. NOTE: This won't change the styles, just the HTML element.

```tsx live
<Flex flexDirection="column" gap="small">
  <Heading as="h2" level={5}>
    This heading is a h2
  </Heading>

  <Accordion titleHeadingLevel={3} title="Accordion title (as h3)">
    Accordion details
  </Accordion>
</Flex>
```

## Controlled vs uncontrolled

By default, the accordion is collapsed but can be expanded on load by passing the `defaultExpanded` prop with the value of `true`.

```tsx live
<Accordion defaultExpanded title="Accordion title">
  Accordion details expanded on load
</Accordion>
```

If you need to control the open and close state of the accordion, you can use the `expanded` and `onExpandedChange` props.

## Weight

There are two options for `weight`: `bold` (default) and `subtle`. It's best to keep weights the same across each `Accordion` in the same group. This provides consistency and the best user experience.

### Bold (default)

The `bold` weight is best for pages with ample space and at large screen sizes.

```tsx live
<Accordion title="Accordion title (bold)">Accordion details</Accordion>
```

### Subtle

`subtle` weight is best used when space is constricted, e.g. in a card, tile, modal or side panel.

```tsx live
<Accordion weight="subtle" title="Accordion title (subtle)">
  Accordion details
</Accordion>
```

## Spacing

Spacing around the title text and details can be controlled by the `density` prop. Consistency across each `Accordion` in a group is important for readability, as with the `weight`.

### Regular (default)

```tsx live
<Accordion title="Accordion title (regular)">Accordion details</Accordion>
```

### Spacious

```tsx live
<Accordion density="spacious" title="Accordion title (spacious)">
  Accordion details
</Accordion>
```

### Slim

```tsx live
<Accordion density="slim" title="Accordion title (slim)">
  Accordion details
</Accordion>
```

## Align expand indicator

By default the expand indicator (chevron) is placed on the right side of the header. The `alignExpandIndicator` prop allows for the title on the left side to vertically align with other element titles in the layout. Aligning the indicator to the left can be useful in large layouts where it may get overlooked, given the distance the user's eye needs to travel.

### Right (default)

```tsx live
<Accordion title="Accordion title (right indicator)">Accordion details</Accordion>
```

### Left

```tsx live
<Accordion alignExpandIndicator="left" title="Accordion title (left indicator)">
  Accordion details
</Accordion>
```

## Panel padding

By default, the accordion panel has horizontal and vertical padding applied. The `noPanelPadding` prop allows you to remove this padding when you need full-width content or custom spacing.

### Without padding

```tsx live
<Accordion noPanelPadding title="Accordion with no panel padding">
  Accordion details without panel padding
</Accordion>
```

## Header items

The `items` prop allows you to add interactive or static content to the end of the accordion header. It accepts an array of objects, each specifying the type of element to display and its associated properties.

```tsx live
const headerItems: AccordionItem[] = [
  {
    // Use the `node` type to render any custom React node via the `children` property
    type: 'node',
    children: <Badge label="Badge" tone="neutral" />,
  },
  {
    // Use the `button` type along with props for the `Button` component
    type: 'button',
    label: 'Button',
    onClick: console.info,
    size: 'small',
    tone: 'neutral',
  },
  {
    // Use the `actionsDropdown` type along with props for the `ActionsDropdown` component
    type: 'actionsDropdown',
    size: 'small',
    tone: 'neutral',
    trigger: (ref: React.RefObject<HTMLButtonElement>, isOpen?: boolean) => (
      <Button
        icon={isOpen ? ChevronUpIcon : ChevronDownIcon}
        iconPlacement="right"
        label="ActionsDropdown"
        pressed={isOpen}
        ref={ref}
        size="small"
        tone="neutral"
      />
    ),
    actions: [
      { label: 'Action 1', onClick: console.info, tone: 'neutral' },
      { label: 'Action 2', onClick: console.info, tone: 'neutral' },
    ],
  },
];

return (
  <Accordion density="spacious" items={headerItems} title="Accordion title">
    Accordion details
  </Accordion>
);
```

## Title item

The `titleItem` prop allows you to add supplementary content next to the accordion's title, such as a `Tag`, `Badge`, `NumberBadge`, or `Text` component. Only one `titleItem` can be shown per accordion header.

```tsx live
<Accordion
  title="Accordion title"
  titleItem={{
    type: 'tag',
    label: 'Tag title item',
    size: 'small',
    weight: 'outlined',
  }}
>
  Accordion details
</Accordion>
```

## Custom header migration

The `customHeader` prop has been **deprecated** and will be **removed in the next major version**. Instead, use the `titleItem` or `items` prop for a structured and accessible way to add interactive or static content to the accordion header.

### Before (using `customHeader`)

Previously, the `customHeader` prop accepted a function that returned a custom component. This was primarily used to add action buttons to the accordion header.

```tsx live
<Accordion
  customHeader={() => (
    <Flex justifyContent="space-between" alignItems="center" width="100%">
      {/* Emulate default text styles for the accordion header */}
      <Flex gap="small">
        <Text color="neutralBold" fontFamily="sans" fontSize="standard" fontWeight="bold" lineHeight="tight">
          A custom header
        </Text>
        <NumberBadge number={3} />
      </Flex>
      {/* Custom button */}
      <Button label="Header action" onClick={console.info} size="small" />
    </Flex>
  )}
>
  Accordion details
</Accordion>
```

### After (using `titleItem` and `items`)

Now, instead of providing a function, pass an object to the `titleItem` prop and an array to the `items` prop.

```tsx live
<Accordion
  title="A custom header"
  titleItem={{
    type: 'numberBadge',
    number: 3,
  }}
  items={[
    {
      type: 'button',
      label: 'Header action',
      onClick: console.info,
      size: 'small',
    },
  ]}
>
  Accordion details
</Accordion>
```

## Accordion group

To consistently group a set of accordions, you can use the `<AccordionGroup />` component. This will stack the accordions with consistent spacing. You can also make the group discoverable as a landmark by screen readers by passing in an `ariaLabel`. It's important to keep the `density`, `weight` and `alignExpandIndicator` values consistent across each accordion in the group.

```tsx live
const accordions = [
  {
    title: 'Australia',
    details: 'The capital city of Australia is Canberra. The estimated population of Canberra is 395 790 people.',
  },
  {
    title: 'Brazil',
    details: 'The capital city of Brazil is Brasília. The estimated population of Brasilia is 4 873 000 people.',
  },
  {
    title: 'Sweden',
    details: 'The capital city of Sweden is Stockholm. The estimated population of Stockholm is 975 551 people.',
  },
];

return (
  <AccordionGroup weight="subtle" ariaLabel="Capital cities">
    {accordions.map(({ title, details }) => (
      <Accordion density="spacious" weight="subtle" title={title} key={title}>
        {details}
      </Accordion>
    ))}
  </AccordionGroup>
);
```

## Icon

The `icon` prop renders an icon to the left of the heading. It's always hidden on smaller screens to ensure enough space for important content.

```tsx live
<Flex flexDirection="column" gap="medium">
  <Accordion icon={TargetIcon} title="Spacious Accordion" weight="bold" density="spacious">
    Accordion details
  </Accordion>
  <Accordion icon={TargetIcon} title="Regular Accordion" weight="bold">
    Accordion details
  </Accordion>
  <Accordion icon={TargetIcon} title="Slim Accordion" weight="bold" density="slim">
    Accordion details
  </Accordion>
</Flex>
```

An interactive heading that reveals an associated section of content.

Accordion

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources