A toolkit of Angular directives designed to construct a fully customizable accordion, enabling developers to define interactive, collapsible content areas tailored to specific application needs.
Installation
Add and import the module into your imports section.
Module
Standalone directives
Anatomy
Directive's set structure.
Input props
AccordionRoot Attribute
The root directive for the accordion. Handles the accordion state, configuration and keyboard navigation.
| Input | Default | Type | Required |
|---|---|---|---|
| value | "[ ]" | string | string[] | false |
| multiple | false | boolean | false |
| orientation | "vertical" | "vertical" | "horizontal" | false |
| collapsible | false | boolean | false |
| disabled | false | boolean | false |
| Output | Description | Returns |
|---|---|---|
| itemChange | Returns the opened items | string | string[] |
| Attribute | Value |
|---|---|
| data-orientation | "vertical" | "horizontal" |
AccordionItem Attribute
| Input | Default | Type | Required |
|---|---|---|---|
| value* | — | string | true |
| disabled | false | boolean | false |
| Attribute | Value |
|---|---|
| data-state | "open" | "closed" |
| data-disabled | Shows when disabled |
| data-orientation | "vertical" | "horizontal" |
AccordionHeader Attribute Optional
Use this directive when your trigger is inside an non heading element (h1, h2...) to apply the correct accessibility rules.
| Input | Default | Type | Required |
|---|---|---|---|
| accordionHeader* | — | number | true |
| Attribute | Value |
|---|---|
| data-state | "open" | "closed" |
| data-disabled | Shows when disabled |
| data-orientation | "vertical" | "horizontal" |
AccordionTrigger Attribute
Toggle the accordion item and changes its state.
| Attribute | Value |
|---|---|
| data-state | "open" | "closed" |
| data-disabled | Shows when disabled |
| data-orientation | "vertical" | "horizontal" |
AccordionContent Attribute
Contains the collapsible content for an accordion item.
| Attribute | Value |
|---|---|
| data-state | "open" | "closed" |
| data-disabled | Shows when disabled |
| data-orientation | "vertical" | "horizontal" |
State
AccordionRootDirective injects an accordion state and exposes an API to interact with the items. Most of the time you wouldn't need it, but it is accessible within the template and it can be useful when we create a new directive or component to replace one of the current directives blocks. Each directive injects the root instance to handle the accordion accessibility and logic.
Access directive API with exportAS
We can access the state of the accordion using a template variable. All the directives expose themself with the same name, for example, in the previous demo we are using #accItem="accordionItem". With accItem we have access to the directive's attributes and also the state service.
Example
We could use it with any other directive. For example with #image="vacAvatarRoot" and access the state.
State API - AccordionStateService
Documentation for the accordion state service API.
Variables
| Name | Type | Default |
|---|---|---|
| items | WritableSignal<AccordionItem[]> | [ ] |
| itemsCount | Signal<number> | 0 |
| multiple | WritableSignal<boolean> | false |
| collapsible | WritableSignal<boolean> | false |
| disabled | WritableSignal<boolean> | false |
| value | WritableSignal<string | []> | [] |
| orientation | WritableSignal<"vertical" | "horizontal"> | "vertical" |
Methods
| Method | Arguments | Return |
|---|---|---|
| getConfig | — | AccordionConfig |
| isActive | (id: string) | boolean |
| isInitiallyOpen | (id: string) | boolean |
| addItem | (item: AccordionItem) | Map<string, ElementRef<HTMLE>> |
| getTriggers | — | boolean |
| bindTrigger | (id: string, trigger: ElementRef<HTMLElement>) | void |
| removeTrigger | (id: string) | void |
| removeItem | (id: string) | void |
| openItem | (id: string, foce = false) | void |
| closeItem | (id: string, foce = false) | void |
| toggleItem | (id: string, foce = false) | void |
| closeAllItems | — | void |
| getItem | (id: string) | AccordionItem | null |
| generateAriaControlId | (uniqueId: string, value: string, type: "trigger" | "panel") | string |
Types
Avatar types that you can import.
Accessibility
This accordion component is designed in accordance with the WAI-ARIA Authoring Practices Guide. For more details on accessibility features and guidelines, please refer to the WAI-ARIA Accordion Practices. This ensures our component meets modern accessibility standards, providing an inclusive user experience.
Keyboard Navigation
Keyboard navigation uses an internal directive system to control the keyboard flow. You can read more about it in KeyboardNavigationDirective. KeyboardNavigationDirective props are extended directly in the AccordionRoot directive.
| Key | Description |
|---|---|
| ArrowUp | When orientation is vertical, it moves the focus to the previous trigger. |
| ArrowDown | When orientation is vertical, it moves the focus to the next trigger. |
| ArrowRight | When orientation is horizontal, it moves the focus to the next trigger |
| ArrowLeft | When orientation is horizontal, it moves the focus to the previous trigger |
| Tab | Move focus to the next trigger. |
| Shift + Tab | Move focus to the previous trigger. |
| Space | Toggle the focused accordion item. |
| Enter | Toggle the focused accordion item. |
| Home | Navigates to the first accordion toggle. |
| End | Navigates to the last accordion toggle. |
Examples
Build a custom trigger using the accordion state
We can create custom components/directives that will interact with the accordion state. It can be useful when we need to implement custom logic into one or more of our pieces. Remember we could use the AccordionTriggerDirective inside our component instead of implementing our custom logic. To continue, create a component wrap for the desired functionality and implement your custom logic. Remember to implement the necessary accessibility attributes.
Once we created our trigger component. We can implement it inside the root directive.