ruclib-accordion

This library provides a flexible and customizable accordion component for your Angular applications, allowing users to efficiently organize and display content in collapsible panels.

Features

• Dynamic Panels: Create any number of accordion panels, each with its own header and content.
• Multiple Expansion: Configure the accordion to allow multiple panels to be expanded simultaneously.
• Customizable Appearance:
  • Apply custom colors to panel titles, headers, and borders.
  • Use text, an icon, or an image for the panel title.
  • Customize the toggle icon and its position (before or after the title).
• Flexible Content: Panel content can be simple text, HTML, or even other Angular components like forms and data grids.
• Expansion Direction: Control the direction in which panels expand (vertically or horizontally).
• Lazy Loading: Lazily load panel content to improve performance.
• Accessibility: Panels can be enabled, disabled, and their initial expanded state can be configured.

Installation Guide

Install the Entire Library

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the Accordion component:

For Angular 15:

npm install @ruc-lib/[email protected] @angular/material@^15.0.0 @angular/cdk@^15.0.0

For Angular 16:

npm install @ruc-lib/[email protected] @angular/material@^16.0.0 @angular/cdk@^16.0.0

For Angular 17:

npm install @ruc-lib/[email protected] @angular/material@^17.0.0 @angular/cdk@^17.0.0

For Angular 18:

npm install @ruc-lib/[email protected] @angular/material@^18.0.0 @angular/cdk@^18.0.0

For Angular 19:

npm install @ruc-lib/[email protected] @angular/material@^19.0.0 @angular/cdk@^19.0.0

For Angular 20:

npm install @ruc-lib/[email protected]

Note: When installing in Angular 15-19 apps, you must specify the matching @angular/material and @angular/cdk versions to avoid peer dependency conflicts. Angular 20 will automatically use the correct versions.

📦 Version Compatibility

| Angular Version | Compatible Version | Installation Command | |-----------------|--------------------|----------------------------------------------------------------------------------------| | 15.x.x | 3.2.0 | npm install @ruc-lib/accordion@^3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0 | | 16.x.x | 3.2.0 | npm install @ruc-lib/accordion@^3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0 | | 17.x.x | 4.0.0 | npm install @ruc-lib/accordion@^4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0 | | 18.x.x | 4.0.0 | npm install @ruc-lib/accordion@^4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0 | | 19.x.x | 4.0.0 | npm install @ruc-lib/accordion@^4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0 | | 20.x.x | 4.0.0 | npm install @ruc-lib/accordion@^4.0.0 |

Usage

1. Import the Component

In your Angular component file (e.g., app.component.ts), import the RuclibAccordionComponent:

import { Component } from '@angular/core';

// For Complete Library
import { RuclibAccordionComponent } from '@uxpractice/ruc-lib/accordion';

// For Individual Package
import { RuclibAccordionComponent } from '@ruc-lib/accordion';

@Component({
  selector: 'app-root',
  imports: [RuclibAccordionComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}

2. Use the Component

In your component's template, use the <uxp-ruclib-accordion> selector:

<uxp-ruclib-accordion
    [rucInputData]="inputObjectAccordion"
    (rucEvent)="passEvent($event)"
    [customTheme]="customTheme">
</uxp-ruclib-accordion>

API Reference

Component Inputs

| Input | Type | Description | |----------------|--------------------------|-----------------------------------------------------| | rucInputData | AccordionInterface | The main configuration object for the accordion. | | customTheme | string | An optional CSS class for custom theming. |

Component Outputs

| Output | Type | Description | |------------|-------|----------------------------------------------| | rucEvent | any | Emits events from the accordion panels. |

rucInputData (AccordionInterface)

This is the main configuration object for the Accordion component.

| Property | Type | Description | |----------------------|-----------------------------|---------------------------------------------------------------------------------------------------------| | isExpandMultiPanel | boolean | If true, multiple panels can be expanded at the same time. Default is true. | | displayMode | MatAccordionDisplayMode | The display mode of the accordion. Can be 'default' or 'flat'. Default is 'default'. | | enableExpandAllBtn | boolean | If true, shows a button to expand all panels. Default is false. | | expandAllBtnName | string | Custom text for the "Expand All" button. | | enableCollapseAllBtn| boolean | If true, shows a button to collapse all panels. Default is false. | | collapseAllBtnName | string | Custom text for the "Collapse All" button. | | allBtnPosition | string | Position of the "Expand/Collapse All" buttons. Can be 'start', 'center', or 'end'. | | panelContent | PanelContentInterface[] | An array of panel configuration objects. |

panelContent Item

This object defines the configuration for each panel in the accordion.

| Property | Type | Description | |--------------------------------|------------------------------------|---------------------------------------------------------------------------------------------------------| | panelId | number | A unique identifier for the panel. | | panelTitle | string | The title text displayed in the panel header. | | isPanelTitleImage | boolean | If true, an image is used as the panel title. | | panelTitleImagePath | string | The path to the image for the panel title. | | isPanelTitleIcon | boolean | If true, an icon is used as the panel title. | | panelTitleIconName | string | The name of the Material Icon for the panel title. | | panelDescription | string | A description displayed below the panel title. | | panelContentType | string | The type of content in the panel. Can be 'text', 'html', 'datagrid', etc. Default is 'text'. | | panelContentData | object | An object containing the data for the panel content. | | isDisabled | boolean | If true, the panel is disabled and cannot be interacted with. | | isExpanded | boolean | The initial expanded state of the panel. | | isCustomToggleIcon | boolean | If true, a custom toggle icon is used. | | toggleIconName | string | The name of the custom Material Icon for the toggle indicator. | | isHideToggleIcon | boolean | If true, the toggle indicator icon is hidden. | | toggleIconPosition | MatAccordionTogglePosition | The position of the toggle icon. Can be 'before' or 'after'. Default is 'after'. | | panelExpandDirection | string | The direction in which the panel expands. Can be 'vertical' or 'horizontal'. | | headerButtonColor | string | Custom color for the panel header. | | panelHeaderButtonColor | string | Custom color for the panel header button. | | isToggleHeaderButtonColor | boolean | If true, enables a different color for the header when the panel is expanded. | | togglePanelHeaderButtonColor | string | The color of the header when the panel is expanded. | | panelHeaderButtonBorder | string | Custom border for the panel header button. | | isToggleHeaderButtonBorder | boolean | If true, enables a different border for the header when the panel is expanded. | | headerButtonBorder | string | Custom border for the header. | | togglePanelHeaderButtonBorder| string | The border of the header when the panel is expanded. |

Example Configuration

Here's an example of how to configure the Accordion component in your component's TypeScript file.

import { Component } from '@angular/core';

// For Complete Library
import { RuclibAccordionModule, AccordionInterface, PanelContentInterface } from '@uxpractice/ruc-lib/accordion';

// For Individual package
import { RuclibAccordionModule, AccordionInterface, PanelContentInterface } from '@ruc-lib/accordion';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  customTheme = 'ruc-custom-theme';

  inputObjectAccordion: AccordionInterface = {
    isExpandMultiPanel: true,
    displayMode: 'default',
    panelContent: [
        {
            panelId: 1,
            panelTitle: 'Personal Information',
            isPanelTitleImage: false,
            panelTitleImagePath: '',
            isPanelTitleIcon: true,
            panelTitleIconName: 'account_circle',
            panelDescription: 'View and edit your personal details',
            panelContentType: 'text',
            panelContentData: {
                dataSource: 'Here you can add a form or other components to manage personal information.',
                inputObjectDataGrid: ''
            },
            isDisabled: false,
            isExpanded: true,
            isCustomToggleIcon: false,
            toggleIconName: '',
            isHideToggleIcon: false,
            toggleIconPosition: 'after',
            panelExpandDirection: 'vertical',
            headerButtonColor: '',
            panelHeaderButtonColor: '',
            isToggleHeaderButtonColor: false,
            togglePanelHeaderButtonColor: '',
            panelHeaderButtonBorder: '',
            isToggleHeaderButtonBorder: false,
            headerButtonBorder: '',
            togglePanelHeaderButtonBorder: '',
        }
    ]
  };

    passEvent(event: any) {
    console.log('Accordion Event:', event);
  }
}

⚠️ IMPORTANT: Custom Theme Usage in Angular Material

When implementing custom themes, such as:

.custom-theme-1 {
  @include angular-material-theme($custom-theme);
}

// You must also include the typography mixin to ensure text styles are applied correctly as shown below:
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
  @include mat.typography-level($theme-custom-typography-name, body-1);
}

Contribution

Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

Acknowledgements

Thank you for choosing the Accordion component. If you have any feedback or suggestions, please let us know!