---
examples:
 - name: basic
   label: Basic Accordion
   description: Accordion with a pre-selected open section, and a button that programmatically opens another section. By default, only one section can be open at a time. You can close a section by opening another section.
 - name: conditional
   label: Accordion with Conditional Section
   description: Accordion sections can be toggled to be visible or not.
 - name: multiple
   label: Accordion with Multiple Open Sections
   description: Accordion sections can be open or closed without restrictions, programmatically or by clicking the section headers.
---

A `lightning-accordion` displays vertically stacked sections of content that you can expand and collapse. Click a section's header to expand its content. Users can control how much content is visible at once, and don't need to scroll as much to see the content of a page.

To create an accordion section, nest a `lightning-accordion-section` component within `lightning-accordion`. Each `lightning-accordion-section` can contain HTML markup or Lightning components.

This component inherits styling from [accordion](https://www.lightningdesignsystem.com/components/accordion) in the Lightning Design System.

To additionally style this component, use Lightning Design System classes in [Utilities](https://www.lightningdesignsystem.com/utilities/alignment).

By default, only one section can be open at a time. You can close a section by opening another section. You can configure the accordion to allow multiple sections to be open, and then the sections can be opened and closed by clicking section headers.

You can specify one or multiple active sections. Active sections are expanded when the component loads. The terms "active", "expanded", and "open" are used interchangeably in this documentation.


#### Initializing the Accordion with An Active Section

The first accordion section is expanded by default. To change the default, provide a section name using the `active-section-name` attribute. The section name is case-sensitive.

This example creates a basic accordion with three sections, where section B is expanded by default. Only one accordion section is expanded at a time.

```html
<template>
   <lightning-accordion active-section-name="B">
     <lightning-accordion-section name="A" label="Accordion Title A">This is the content area for section A</lightning-accordion-section>
     <lightning-accordion-section name="B" label="Accordion Title B">This is the content area for section B</lightning-accordion-section>
     <lightning-accordion-section name="C" label="Accordion Title C">This is the content area for section C</lightning-accordion-section>
   </lightning-accordion>
</template>
```

If two or more sections use the same name and that name is also specified as the `active-section-name`, the first section with that name is expanded by default.

#### Initializing the Accordion with Multiple Active Sections

To specify multiple expanded sections, include `allow-multiple-sections-open` in your markup and pass in an array of accordion section names to `active-section-name`.
If you don't pass in a section name, all sections are closed by default.

```html
<template>
    <lightning-accordion allow-multiple-sections-open
                         active-section-name={activeSections}>
        <lightning-accordion-section name="A" label="Accordion Title A">
            <p>This is the content area for section A.</p>
        </lightning-accordion-section>

        <lightning-accordion-section name="B" label="Accordion Title B">
            <p>This is the content area for section B.</p>
        </lightning-accordion-section>

        <lightning-accordion-section name="C" label="Accordion Title C">
            <p>This is the content area for section C.</p>
        </lightning-accordion-section>
    </lightning-accordion>
</template>
```

In your JavaScript code, define the sections you want to expand.

```javascript
import { LightningElement, track } from 'lwc';

export default class LightningExampleAccordionMultiple extends LightningElement {
    @track activeSections = ['A', 'C'];
}

```

#### Handling the Section Toggle Event

When the open sections change, use the `onsectiontoggle` handler to find out which sections are active.

This example displays the name of the active section.

```html
<template>
    <p>{activeSectionsMessage}</p>

    <lightning-accordion allow-multiple-sections-open
                         onsectiontoggle={handleSectionToggle}
                         active-section-name="A">
        <lightning-accordion-section name="A" label="Accordion Title A">
            <p>This is the content area for section A.</p>
        </lightning-accordion-section>

        <lightning-accordion-section name="B" label="Accordion Title B">
            <p>This is the content area for section B.</p>
        </lightning-accordion-section>

        <lightning-accordion-section name="C" label="Accordion Title C">
            <p>This is the content area for section C.</p>
        </lightning-accordion-section>
    </lightning-accordion>
</template>
```
Use the `detail.openSections` property to return the active section names.

```javascript
import { LightningElement, track } from 'lwc';

export default class DemoAccordionMultiple extends LightningElement {
    @track activeSectionsMessage = '';

    handleSectionToggle(event) {
        const openSections = event.detail.openSections;

        if (openSections.length === 0) {
            this.activeSectionsMessage = 'All sections are closed';
        } else {
            this.activeSectionsMessage =
                'Open sections: ' + openSections.join(', ');
        }
    }
}

```

#### Expanding Sections Programmatically

To expand a section using JavaScript, pass in the section name using `active-section-name`.

This example expands section B when the **Expand Section B** button is pressed.

```html
<template>
    <lightning-button label="Expand Section B"
            onclick={handleClick}>
    </lightning-button>
    <lightning-accordion
        active-section-name={section}
        onsectiontoggle={handleSectionToggle}>
        <lightning-accordion-section name="A" label="A">Content A</lightning-accordion-section>
        <lightning-accordion-section name="B" label="B">Content B</lightning-accordion-section>
        <lightning-accordion-section name="C" label="C">Content C</lightning-accordion-section>
    </lightning-accordion>
</template>
```

The `onclick` handler on the button sets the active section name, which opens the section programmatically.

Use a tracked value to update the section dynamically. Set the tracked value using the `openSections` property in the `onsectiontoggle` handler.

```javascript
import { LightningElement, track } from 'lwc';

export default class App extends LightningElement {
    @track section = '';

    handleClick(event) {
        this.section = "B";
    }

    handleSectionToggle(event){
        this.section = event.detail.openSections;
    }
}

```

To expand multiple sections programmatically, include `allow-multiple-sections-open` in your markup and pass in an array of section names instead.

```javascript
import { LightningElement, track } from 'lwc';

export default class App extends LightningElement {
    @track section = [];

    handleClick(event) {
        this.section = ['B', 'C'];
    }

    handleSectionToggle(event){
            this.section = event.detail.openSections;
    }
}
```

#### Nested Accordions

You can nest `lightning-accordion` components inside `lightning-accordion-section` components to create multiple levels in the accordion. The chevron icon is used for all sections and levels.


#### Usage Considerations

You can't initialize an accordion with multiple sections using only markup. Pass the array of section names using JavaScript, as described in **Initializing the Accordion with Multiple Active Sections**.

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](docs/component-library/documentation/lwc/lwc.migrate_map_aura_lwc_components) in the Lightning Web Components Developer Guide.

#### Custom Events

**`sectiontoggle`**

The event fired when an accordion section is toggled.

The `sectiontoggle` event returns the following parameter.

Parameter|Type|Description
-----|-----|----------
openSections|object|The name of the active section. Returns an array if multiple sections are opened.

The event properties are as follows.

Property|Value|Description
-----|-----|----------
bubbles|false|This event does not bubble.
cancelable|false|This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event.
composed|false|This event does not propagate outside the template in which it was dispatched.
