Angular Accordion Component Overview

    What is Angular Accordion?

    The Angular Accordion is a GUI component for building vertical expandable panels with clickable headers and associated content sections, displayed in a single container. The accordion is commonly used to reduce the need of scrolling across multiple sections of content on a single page. It offers keyboard navigation and API to control the underlying panels' expansion state.

    Users are enabled to interact and navigate among a list of items, such as thumbnails or labels. Each one of those items can be toggled (expanded or collapsed) in order to reveal the containing information. Depending on the configuration, there can be a single or multiple expanded items at a time.

    Angular Accordion Example

    The following is a basic Angular Accordion example of a FAQ section. It operates as an accordion, with individually working sections. You can toggle each text block with a single click, while expanding multiple panels at the same time. This way you can read information more easily, without having to go back and forth between an automatically expanding and collapsing panel, which conceals the previously opened section every time.

    In it, you can see how to define an igx-accrodion and its expansion panels. The sample also demonstrates the two types of expansion behavior. The switch button sets the singleBranchExpand property to toggle between single and multiple branches to be expanded at a time.

    How to install angular accordion?

    Getting Started with Ignite UI for Angular Accordion

    To get started with the Ignite UI for Angular Accordion component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command:

    ng add igniteui-angular
    

    For a complete introduction to the Ignite UI for Angular, read the getting started topic.

    The next step is to import the IgxAccordionModule in your app.module file.

    // app.module.ts
    
    ...
    import { IgxAccordionModule } from 'igniteui-angular';
    
    @NgModule({
        ...
        imports: [..., IgxAccordionModule],
        ...
    })
    export class AppModule {}
    

    Now that you have the Angular Material Accordion module imported, you can start with a basic configuration of the igx-accordion and its panels.

    Usage

    Each section in the IgxAccordionComponent is defined using an expansion panel. Panels provide disabled, collapsed and animationSettings properties, which give you the ability to configure the states of the panel as per your requirement.

    Declaring an accordion

    The accordion wraps all igx-expansion-panels declared inside it.

    <igx-accordion #accordion [singleBranchExpand]="true">
         <igx-expansion-panel>
            <igx-expansion-panel-header>
                <igx-expansion-panel-title>Title Panel 1</igx-expansion-panel-title>
            </igx-expansion-panel-header>
            <igx-expansion-panel-body>
                Content Panel 1
            </igx-expansion-panel-body>
        </igx-expansion-panel>
        <igx-expansion-panel>
            <igx-expansion-panel-header>
                <igx-expansion-panel-title>Title Panel 2</igx-expansion-panel-title>
            </igx-expansion-panel-header>
            <igx-expansion-panel-body>
                Content Panel 2
            </igx-expansion-panel-body>
        </igx-expansion-panel>
    </igx-accordion>
    

    Using the panels accessor you can get a reference to the collection containing all expansion panels children of the igx-accordion.

    @ViewChild('accordion', { static: true })
    public accordion!: IgxAccordionComponent;
    
    this.accordion.panels;
    

    As demonstrated above, the singleBranchExpand property gives you the ability to set whether single or multiple panels can be expanded at a time.

    Angular Accordion Animations

    Angular Accordion supports animations for both expanding and collapsing actions of the panels. Animation behavior can be customized. Normally, animations can be set for each expansion panel individually. However, it could also be applied to all panels at once on IgxAccordionComponent level. This gives users the ability to disable animations for all sections at once via the animations property of the IgxAccordionComponent.

    With regards to animation, you have two options. First, you could set the animationSettings property on the accordion component:

    import { useAnimation } from "@angular/animations";
    import { slideInLeft, slideOutRight } from 'igniteui-angular';
    @Component({
        ...
    })
    export class AccordionComponent {
        public animationSettingsCustom = {
            closeAnimation: useAnimation(slideOutRight, {
                params: {
                    duration: "100ms",
                    toPosition: "translateX(25px)"
                }
            }),
            openAnimation: useAnimation(slideInLeft, {
                params: {
                    duration: "500ms",
                    fromPosition: "translateX(-15px)",
                    startOpacity: 0.1
                }
            })
        };
    }
    

    As you can see, we are using slideInLeft and slideOutRight animations from our inbuilt suite of animations to make the component content appear from the left side and disappear to the right when collapsing the content. We further customize the animations by overriding some of the animations' parameters.

    The following snippet demonstrates passing the animation settings to the component:

    <igx-accordion #accordion [animationSettings]="animationSettingsCustom">
        ...
    </igx-accordion>
    

    Note: If you would like to turn off the animation for the IgxAccordionComponent the animationSettings could be set to null.

    Alternatively, you have the ability to set every single expansion panel`s animationSettings input.

    <igx-accordion #accordion [singleBranchExpand]="true">
         <igx-expansion-panel [animationSettings]="slideLeftRightSettings">
            <igx-expansion-panel-header>
                <igx-expansion-panel-title>Title Panel 1</igx-expansion-panel-title>
            </igx-expansion-panel-header>
            <igx-expansion-panel-body>
                Content Panel 1
            </igx-expansion-panel-body>
        </igx-expansion-panel>
        <igx-expansion-panel [animationSettings]="slideTopBottomSettings">
            <igx-expansion-panel-header>
                <igx-expansion-panel-title>Title Panel 2</igx-expansion-panel-title>
            </igx-expansion-panel-header>
            <igx-expansion-panel-body>
                Content Panel 2
            </igx-expansion-panel-body>
        </igx-expansion-panel>
    </igx-accordion>
    

    Using the collapseAll and expandAll methods you can respectively collapse and expand all IgxExpansionPanels of the IgxAccordion programmatically.

    Note: If singleBranchExpand property is set to true calling expandAll method would expand only the last panel.

    Angular Accordion Templating Example

    With the Angular Accordion component, you can customize the header and content panel`s appearance. The sample below demonstrates how elaborate filtering options can be implemented using the built-in templating functionality of the IgxExpansionPanel.

    Nested Angular Accordions Scenario

    In the following Angular accordion example, we are going to create a complex FAQ section in order to illustrate how you can go about this common application scenario. In the sample nested IgxAccordionComponent is achieved by adding an accordion inside the body of an expansion panel.

    <igx-accordion #accordion>
         <igx-expansion-panel>
            <igx-expansion-panel-header>
                <igx-expansion-panel-title>Title Panel 1</igx-expansion-panel-title>
            </igx-expansion-panel-header>
            <igx-expansion-panel-body>
                <igx-accordion #childAccordion>
                    <igx-expansion-panel>
                        <igx-expansion-panel-header>
                            <igx-expansion-panel-title>Title Nested Panel 1</igx-expansion-panel-title>
                        </igx-expansion-panel-header>
                        <igx-expansion-panel-body>
                            Content Nested Panel 1
                        </igx-expansion-panel-body>
                    </igx-expansion-panel>
                    ...
                </igx-accordion>
            </igx-expansion-panel-body>
        </igx-expansion-panel>
        ...
    </igx-accordion>
    

    You can see the result below.

    Keyboard Navigation

    Keyboard navigation in the Angular Material Accordion provides a rich variety of keyboard interactions to the end-user. This functionality is enabled by default and allows end-users to easily navigate through the panels. The IgxAccordionComponent navigation is compliant with W3C accessibility standards and convenient to use.

    Key Combinations

    • Tab - moves the focus to the first(if the focus is before accordion)/next panel
    • Shift + Tab - moves the focus to the last(if the focus is after accordion)/previous panel
    • Arrow Down - moves the focus to the panel below
    • Arrow Up - moves the focus to the panel above
    • Alt + Arrow Down - expands the focused panel in the accordion
    • Alt + Arrow Up - collapses the focused panel in the accordion
    • Shift + Alt + Arrow Down - expands all enabled panels(if singleBranchExpand is set to true expands the last enabled panel)
    • Shift + Alt + Arrow Up - collapses all enabled panels
    • Home - navigates to the FIRST enabled panel in the accordion
    • End - navigates to the LAST enabled panel in the accordion

    Angular Accordion Styling

    The accordion serves only as a container for the underlying panels. Styles can be applied directly through the panel's theme, as described in the styling section of the IgxExpansionPanel topic.

    By design, there is a margin set to the expanded panels, in case that they are positioned within an igx-accordion. In order to modify it there is a property exposed inside the igx-expansion-panel theme. In order to take advantage of the functions exposed by the theming engine, we have to import the index file in our style file:

    @import '~igniteui-angular/lib/core/styles/themes/index';
    

    Following the simplest approach, we create a new theme that extends the igx-expansion-panel-theme and accepts an $expanded-margin parameter.

    $custom-panel-theme: igx-expansion-panel-theme(
        $expanded-margin: 0px
    );
    

    Using CSS Variables

    The last step is to include the component's theme.

    :host {
        @include igx-css-vars($custom-panel-theme);
    }
    

    Using Theme Overrides

    In order to style components in Internet Explorer 11, we have to use a different approach, since CSS variables are not supported there.

    If the component is using the Emulated ViewEncapsulation, it is necessary to penetrate this encapsulation using ::ng-deep. To prevent the custom theme from leaking into other components, make sure to wrap the ::ng-deep in a :host selector:

    :host {
        ::ng-deep {
            @include igx-expansion-panel($custom-panel-theme);    
        }
    }
    

    API Reference

    Additional Resources

    Our community is active and always welcoming new ideas.