diff --git a/docs/angular/src/content/en/components/badge.mdx b/docs/angular/src/content/en/components/badge.mdx new file mode 100644 index 0000000000..ab21c48d81 --- /dev/null +++ b/docs/angular/src/content/en/components/badge.mdx @@ -0,0 +1,449 @@ +--- +title: Angular Badge Component – Ignite UI for Angular | Infragistics | MIT license +description: Display an active count or icon in a predefined style to decorate other components anywhere in an application with Ignite UI for Angular Badge control. +keywords: Angular Badge component, Angular Badge control, Ignite UI for Angular, Angular UI Components +license: MIT +llms: + description: "Angular Badge is a component used in conjunction with avatars, navigation menus, or other components in an application when a visual notification is needed." +--- + +import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; +import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; +import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; + +# Angular Badge Component Overview + +
+Angular Badge is a component used in conjunction with avatars, navigation menus, or other components in an application when a visual notification is needed. Badges are usually designed as icons with a predefined style to communicate information, success, warnings, or errors. +
+ +## Angular Badge Example + + + +
+ +## Getting Started with Ignite UI for Angular Badge + +To get started with the Ignite UI for Angular Badge component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: + +```cmd +ng add igniteui-angular +``` + +For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. + +The next step is to import the `IgxBadgeModule` in your **app.module.ts** file. + +```typescript +// app.module.ts + +... +import { IgxBadgeModule } from 'igniteui-angular/badge'; +// import { IgxBadgeModule } from '@infragistics/igniteui-angular'; for licensed package + +@NgModule({ + ... + imports: [..., IgxBadgeModule], + ... +}) +export class AppModule {} +``` + +Alternatively, as of `16.0.0` you can import the as a standalone dependency. + +```typescript +// home.component.ts + +... +import { IgxBadgeComponent } from 'igniteui-angular/badge'; +// import { IgxBadgeComponent } from '@infragistics/igniteui-angular'; for licensed package + +@Component({ + selector: 'app-home', + template: '', + styleUrls: ['home.component.scss'], + standalone: true, + imports: [IgxBadgeComponent] +}) +export class HomeComponent {} +``` + + +This component uses Material Icons. Add the following link to your `index.html`: `` + + +Now that you have the Ignite UI for Angular Badge module or component imported, you can start with a basic configuration of the `igx-badge` component. + +## Using the Angular Badge Component + +Let's see how the demo sample is done. It's a simple success badge on an avatar. To build that, we need to import the `IgxAvatarModule`, along with the `IgxBadgeModule`: + +```typescript +// app.module.ts +... +import { IgxBadgeModule } from 'igniteui-angular/badge'; +import { IgxAvatarModule } from 'igniteui-angular/avatar'; +// import { IgxBadgeModule, IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package + +@NgModule({ + ... + imports: [..., IgxBadgeModule, IgxAvatarModule], + ... +}) + +export class AppModule {} +``` + +_Alternatively, as of `16.0.0` you can import the and as standalone dependencies._ + +Next, we will add those components to our template: + +```html +
+ + +
+``` + +Using the wrapper, we will position the badge absolutely, covering a little bit of the avatar: + +```scss +.wrapper { + position: relative; + margin-top: 15px; +} + +igx-badge { + position: absolute; + bottom: 0; + left: 28px; +} +``` + +### Badge Shape + +We can change the badge shape through the attribute setting its value to `square`. By default, the shape of the badge is `rounded`. + +```html + +``` + +If everything's done right, you should see the demo sample shown above in your browser. + +### Badge Size + +The size of the badge can be controlled using the `--size` variable. It will make sure that the badge sizes proportionally in both directions. Keep in mind, however, that badges containing text values use the `caption` typography style for its font-size and line-height. For that reason, when setting the `--size` of a badge containing text to values below 16px, you will also need to modify its typography. + +Example: + +```scss +igx-badge { + --size: 12px; + + font-size: calc(var(--size) / 2); + line-height: normal; +} +``` + +### Badge Value and Icon + +Use the `[value]` input to display text or a numeric count inside the badge: + +```html + +``` + +Use the `[icon]` input to display an icon inside the badge: + +```html + +``` + +When both `[icon]` and `[value]` are set, the badge displays both simultaneously: + +```html + + +``` + +Or you can project content directly: + +```html + {{ model.value }} + + + + bluetooth + Bluetooth + +``` + +### Badge Icon + +In addition to material icons, the `igx-badge` component also supports usage of [Material Icons Extended](/material-icons-extended) and any other custom icon set. To add an icon from the material icons extended set inside your badge component, first you have to register it: + +```ts +export class BadgeIconComponent implements OnInit { + constructor (protected _iconService: IgxIconService) {} + + public ngOnInit() { + this._iconService.addSvgIconFromText(heartMonitor.name, heartMonitor.value, 'imx-icons'); + } +} +``` + +Then, just specify the icon name and family as follows: + +```html + +``` + + + +### Outlined Badge + +The `igx-badge` component can also have a subtle border around it when its attribute is set. + +```html + +``` + + + +The color of the border can also be customized with the `$border-color` property from the . + +### Dot Badge + +The `igx-badge` component can also render as a minimal dot indicator for notifications by enabling its property. Dot badges do not support content, but they can be outlined and can use any of the available dot types (e.g., primary, success, info, etc.). + +```html + +``` + + + +### Badge in List + +Let's extend the previous sample and create a list with contacts, similar to those in chat clients. In addition to the contact name, we want to display an avatar and the current state of the contact (online, offline or away). To achieve this, we're using the and components. For a container, is used. + +To continue, include all needed modules and import them in the **app.module.ts** file. + +```typescript +// app.module.ts + +... +import { IgxListModule } from 'igniteui-angular/list'; +import { IgxAvatarModule } from 'igniteui-angular/avatar'; +import { IgxBadgeModule } from 'igniteui-angular/badge'; +// import { IgxListModule, IgxAvatarModule, IgxBadgeModule } from '@infragistics/igniteui-angular'; for licensed package + +@NgModule({ + ... + imports: [..., IgxListModule, IgxAvatarModule, IgxBadgeModule], +}) +export class AppModule {} +``` + + +The has and inputs to configure the badge look. You can set the icon by providing its name from the official [material icons set](https://material.io/icons/). The badge type can be set to either `Default`, `Info`, `Success`, `Warning`, or `Error`. Each type applies a specific background color, which takes precedence over any custom background color. + + +In our sample, and are bound to model properties named _icon_ and _type_. + +Next, we're adding the contacts in our template: + +```html +{/* contacts.component.html */} + + + + Team Members (4) + + +
+
+ + +
+
+ {{ member.name }} +
+
+ + +``` + +We're going to create our members in the typescript file like this: + +```typescript +// contacts.component.ts + +... +public members: Member[] = [ + new Member('Terrance Orta', 'online'), + new Member('Donna Price', 'online'), + new Member('Lisa Landers', 'away'), + new Member('Dorothy H. Spencer', 'offline'), +]; + +``` + +```typescript +... +class Member { + public name: string; + public status: string; + public type: string; + public icon: string; + + constructor(name: string, status: string) { + this.name = name; + this.status = status; + switch (status) { + case 'online': + this.type = 'success'; + this.icon = 'check'; + break; + case 'away': + this.type = 'warning'; + this.icon = 'schedule'; + break; + case 'offline': + this.type = 'error'; + this.icon = 'remove'; + break; + } + } +} +``` + +Position the badge in its parent container: + +```css +/* contacts.component.css */ + +.wrapper { + display: flex; + flex-direction: row; +} + +.contact-name { + font-weight: 600; +} + +.contact-container { + margin-left: 20px; +} + +.badge-style { + position: absolute; + bottom: 2.5px; + left: 40px; +} + +``` + +If the sample is configured properly, a list of members should be displayed and every member has an avatar and a badge, showing its current state. + + + +## Styling + +### Badge Theme Property Map + +Changing the `$background-color` property automatically updates the following dependent properties: + +| Primary Property | Dependent Property | Description | +| --- | --- | --- | +| **$background-color** | $icon-color | The color used for icons in the badge. | +| | $text-color | The color used for text in the badge. | + +To get started with styling the badges, we need to import the `index` file, where all the theme functions and component mixins live: + +```scss +@use "igniteui-angular/theming" as *; + +// IMPORTANT: Prior to Ignite UI for Angular version 13 use: +// @import '~igniteui-angular/lib/core/styles/themes/index'; +``` + +Following the simplest approach, we create a new theme that extends the and accepts some parameters that style the badge's items. When you set the `$background-color`, the `$icon-color` and `$text-color` are automatically assigned based on which offers better contrast—black or white. Note that the `$border-radius` property only takes effect when the badge's is set to `square`. + +```scss +$custom-badge-theme: badge-theme( + $background-color: #57a5cd, + $border-radius: 4px +); +``` + +To include the new theme we use the `tokens` mixin: + +```scss +:host { + @include tokens($custom-badge-theme); +} +``` + +### Demo + + + +### Styling with Tailwind + +You can style the `badge` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. + +Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows: + +```scss +@import "tailwindcss"; +... +@use 'igniteui-theming/tailwind/utilities/material.css'; +``` + +The utility file includes both `light` and `dark` theme variants. + +- Use `light-*` classes for the light theme. +- Use `dark-*` classes for the dark theme. +- Append the component name after the prefix, e.g., `light-badge`, `dark-badge`. + +Once applied, these classes enable dynamic theme calculations. From there, you can override the generated CSS variables using `arbitrary properties`. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.). + +You can find the full list of properties in the . The syntax is as follows: + +```html + + +``` + + +The exclamation mark(`!`) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component’s default theme. + + +At the end your badges should look like this: + + + +
+ +## API References + +- +- +- +- +- +- +## Theming Dependencies + +- + +## Additional Resources + +
+ +Our community is active and always welcoming to new ideas. + +- [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) +- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) diff --git a/docs/angular/src/content/en/components/layouts/accordion.mdx b/docs/angular/src/content/en/components/layouts/accordion.mdx new file mode 100644 index 0000000000..80a82fb1ec --- /dev/null +++ b/docs/angular/src/content/en/components/layouts/accordion.mdx @@ -0,0 +1,370 @@ +--- +title: "Angular Accordion Component | Layouts | Infragistics" +description: "Angular Accordion is a layout component for organizing expandable and collapsible content panels in a vertical container." +keywords: "Angular Accordion, accordion component, expandable panels, Ignite UI for Angular, Infragistics" +license: MIT +last_updated: "2026-07-30" +mentionedTypes: ["Accordion", "ExpansionPanel"] +namespace: Infragistics.Controls +relatedComponents: ["ExpansionPanel"] +llms: + description: "The Ignite UI for Angular Accordion helps developers group related content into expandable and collapsible panels inside a vertical layout." +--- +import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; +import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; +import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import { Image } from 'astro:assets'; +import accordionAnatomy from '@xplat-images/anatomy-frame-light/Accordion-lt.png'; +import accordionDo from '@xplat-images/accordion/accordion_do1.png'; +import accordionDo2x from '@xplat-images/accordion/accordion_do1@2x.png'; +import accordionDoNot from '@xplat-images/accordion/accordion_do_not1.png'; +import accordionDoNot2x from '@xplat-images/accordion/accordion_dont1@2x.png'; + +# Accordion Component + +The Ignite UI for Angular Accordion is a layout component for organizing expandable content panels in a single vertical container. + +## Live Demo + + + +## Anatomy + +The accordion structure consists of an accordion container with one or more expansion panel children. + + + +```text +igx-accordion // host - manages a set of expansion panels +└─ igx-expansion-panel // child panel + ├─ igx-expansion-panel-header // panel header container + │ ├─ igx-expansion-panel-title // panel header title + │ ├─ igx-expansion-panel-description // optional header description + │ └─ igx-expansion-panel-icon // optional custom expand/collapse icon + └─ igx-expansion-panel-body // expandable panel content +``` + +## Getting Started + +### Prerequisites and Version Compatibility + +Use the accordion with the Ignite UI for Angular version installed in your Angular application. Complete the shared [Getting Started](../general/getting-started.mdx) topic before importing the standalone accordion directives. + +Import the standalone accordion directives before you use the component. If you have not set up Ignite UI for Angular yet, complete the shared [Getting Started](../general/getting-started.mdx) topic first. + +```ts +import { Component } from '@angular/core'; +import { IGX_ACCORDION_DIRECTIVES } from 'igniteui-angular/accordion'; + +@Component({ + selector: 'app-accordion', + imports: [IGX_ACCORDION_DIRECTIVES], + templateUrl: './accordion.component.html', +}) +export class AccordionComponent {} +``` + +## Usage + +Build the accordion by placing one or more components inside an container. + +### Single Expansion + +Set to switch between one-open-panel behavior and multiple-open-panel behavior. + +```html + + + + Title Panel 1 + + +

Content Panel 1

+ + + + + Title Panel 2 + + +

Content Panel 2

+ + + +``` + +### Programmatic Expansion + +Use and to collapse or expand the accordion panels programmatically. + + +Calling expands only the last enabled panel when is `true`. + + +```html + + + + + + + Title Panel 1 + + +

Content Panel 1

+ + + + + Title Panel 2 + + +

Content Panel 2

+ + + +``` + + + +### Customize Panel Content + +Customize panel headers with title and description elements, and place expandable content inside the panel body. + +```html + + + + Billing + Payment and invoice settings + + +

Update payment methods, billing contacts, and invoice delivery options.

+ + + +``` + + + +### Nest Accordions + +Nest an accordion inside an expansion panel body when you need a second level of grouped disclosure. + +```html + + + + Account Settings + + + + + + Notifications + + +

Configure email and product notification preferences.

+ + + + + + +``` + + + +### Do/Don't + +**When to use:** Use the accordion when you need to organize secondary content, FAQ entries, settings groups, or other related vertical sections that users expand on demand. Keep panel titles short and descriptive, and enable single-expansion behavior when users should focus on one section at a time. + +**When not to use:** Use the [Expansion Panel](../expansion-panel.mdx) when you need a single standalone expandable section instead of a coordinated container that manages multiple panels together. Do not use an accordion to hide essential primary content or to group unrelated sections. + +
+ + + + + + + + + + + + + +
DoDon't
Angular Accordion do guidanceAngular Accordion don't guidance
+
+ +## Properties + +The accordion exposes container-level controls; panel-specific state is configured on each . + +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| | `boolean` | `false` | Controls whether one or multiple panels can stay expanded at the same time. | +| | `QueryList` | n/a | Returns the collection of child expansion panels in the accordion. | + +## Methods + +Use the accordion methods when you need to change panel state from your code. + +| Name | Description | +| -- | -- | +| | Expands the available panels. | +| | Collapses the available panels. | + +## Styling + +Style the accordion by customizing the appearance of its child components. + + + +### Sass Theming + +Use the function to create a custom expansion panel theme, then include the generated tokens in the component stylesheet. + +```scss +@use "igniteui-angular/theming" as *; + +$custom-panel-theme: expansion-panel-theme( + $header-background: #011627, + $body-background: #f0ece7, + $expanded-margin: 10px +); + +:host { + @include tokens($custom-panel-theme); +} +``` + +### Styling Variables + +| Variable | What it changes | +| -- | -- | +| `$header-background` | The panel header background color. | +| `$header-focus-background` | The panel header background color when focused. | +| `$header-title-color` | The panel header title text color. | +| `$header-description-color` | The panel header description text color. | +| `$header-icon-color` | The panel header icon color. | +| `$body-background` | The panel body background color. | +| `$body-color` | The panel body text color. | +| `$expanded-margin` | The margin applied to expanded panels when they are placed inside an accordion. | +| `$border-radius` | The expansion panel border radius. | + +### Styling with Tailwind + +Use Tailwind utility classes to apply expansion panel theme tokens while keeping the styling close to the component markup. + +```html + + + + Getting Started + Setup and onboarding + + +

Find installation steps, project setup guidance, and resources for building your first application.

+ + + +``` + + + +## Accessibility + +The accordion supports keyboard interaction for moving focus between panels and changing their expanded state. + +### Keyboard Interaction + +Use the keyboard shortcuts below to move through the accordion and open or close panels. + +| Key | Action | +| -- | -- | +| Down Arrow | Moves focus to the panel below. | +| Up Arrow | Moves focus to the panel above. | +| Alt + Down Arrow | Opens the focused panel. | +| Alt + Up Arrow | Closes the focused panel. | +| Shift + Alt + Down Arrow | Opens all enabled panels. If is `true`, opens the last enabled panel. | +| Shift + Alt + Up Arrow | Closes all enabled panels. | +| Home | Moves focus to the first enabled panel. | +| End | Moves focus to the last enabled panel. | + +### Screen Readers / ARIA + +The accordion's accessibility semantics are provided through its child expansion panels and their headers. + +- Each panel header exposes `role="button"`, `aria-expanded`, and `aria-controls`. +- Each panel body exposes `role="region"` and a label through `aria-labelledby` or `aria-label`. +- Use clear title text for each panel so assistive technologies can announce a meaningful label. +- Keep interactive content inside panel bodies in a logical tab order. + +### Accessibility Compliance + +Infragistics documents Ignite UI for Angular accessibility support for Section 508 and WCAG 2.1 guideline areas in the [Accessibility Compliance](../interactivity/accessibility-compliance.mdx) topic. The accordion's compliance evidence comes from the child components that provide the interactive headers and regions. + +| Criterion | How the component complies | +| -- | -- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | The accordion supports keyboard commands for moving focus and opening or closing panels. | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) | Focus moves through enabled panels in sequence, with shortcuts for jumping to the first and last panel. | + +Your responsibilities: + +- Provide panel titles that describe the content behind each disclosure area. +- Preserve a logical focus order in the surrounding page layout. +- Validate any custom styling against your application's contrast and focus-indicator requirements. + +## Troubleshooting + +Use these notes to resolve common accordion setup and behavior questions. + +### Known Limitations + +No additional platform-independent limitations are documented for the accordion. Panel behavior, slots, styling, and accessibility semantics are provided through the child expansion panel components. + +## API References + + + + +## Dependencies + +The accordion depends on for its visible sections. + +## Additional Resources + +Use these resources to continue with Ignite UI for Angular Accordion support, source, and related layout guidance. + +- [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) +- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) + +## Related Components + +Use the [Expansion Panel](../expansion-panel.mdx) when you need a single expandable section instead of a container that coordinates multiple panels. + +## FAQ + + + + Use the accordion when you need to group multiple related expandable sections and manage them as one container. Use an expansion panel for a single standalone disclosure section. + + + Yes. Use the accordion methods shown in Programmatic Expansion to expand or collapse panels from application code. + + + Yes. Place interactive controls inside the panel content area, and keep their tab order logical within the expanded panel. + + diff --git a/docs/angular/src/content/en/images/accordion/accordion_do1.png b/docs/angular/src/content/en/images/accordion/accordion_do1.png new file mode 100644 index 0000000000..148543500f Binary files /dev/null and b/docs/angular/src/content/en/images/accordion/accordion_do1.png differ diff --git a/docs/angular/src/content/en/images/accordion/accordion_do1@2x.png b/docs/angular/src/content/en/images/accordion/accordion_do1@2x.png new file mode 100644 index 0000000000..a7cf23b8cc Binary files /dev/null and b/docs/angular/src/content/en/images/accordion/accordion_do1@2x.png differ diff --git a/docs/angular/src/content/en/images/accordion/accordion_do_not1.png b/docs/angular/src/content/en/images/accordion/accordion_do_not1.png new file mode 100644 index 0000000000..2cd85c19bc Binary files /dev/null and b/docs/angular/src/content/en/images/accordion/accordion_do_not1.png differ diff --git a/docs/angular/src/content/en/images/accordion/accordion_dont1@2x.png b/docs/angular/src/content/en/images/accordion/accordion_dont1@2x.png new file mode 100644 index 0000000000..61f5c80b74 Binary files /dev/null and b/docs/angular/src/content/en/images/accordion/accordion_dont1@2x.png differ diff --git a/docs/angular/src/content/en/images/anatomy-frame-light/Accordion-lt.png b/docs/angular/src/content/en/images/anatomy-frame-light/Accordion-lt.png new file mode 100644 index 0000000000..d13af44d2a Binary files /dev/null and b/docs/angular/src/content/en/images/anatomy-frame-light/Accordion-lt.png differ diff --git a/docs/xplat/src/assets/images/accordion/accordion_do1.png b/docs/xplat/src/assets/images/accordion/accordion_do1.png new file mode 100644 index 0000000000..148543500f Binary files /dev/null and b/docs/xplat/src/assets/images/accordion/accordion_do1.png differ diff --git a/docs/xplat/src/assets/images/accordion/accordion_do1@2x.png b/docs/xplat/src/assets/images/accordion/accordion_do1@2x.png new file mode 100644 index 0000000000..a7cf23b8cc Binary files /dev/null and b/docs/xplat/src/assets/images/accordion/accordion_do1@2x.png differ diff --git a/docs/xplat/src/assets/images/accordion/accordion_do_not1.png b/docs/xplat/src/assets/images/accordion/accordion_do_not1.png new file mode 100644 index 0000000000..2cd85c19bc Binary files /dev/null and b/docs/xplat/src/assets/images/accordion/accordion_do_not1.png differ diff --git a/docs/xplat/src/assets/images/accordion/accordion_dont1@2x.png b/docs/xplat/src/assets/images/accordion/accordion_dont1@2x.png new file mode 100644 index 0000000000..61f5c80b74 Binary files /dev/null and b/docs/xplat/src/assets/images/accordion/accordion_dont1@2x.png differ diff --git a/docs/xplat/src/assets/images/anatomy-frame-light/Accordion-lt.png b/docs/xplat/src/assets/images/anatomy-frame-light/Accordion-lt.png new file mode 100644 index 0000000000..d13af44d2a Binary files /dev/null and b/docs/xplat/src/assets/images/anatomy-frame-light/Accordion-lt.png differ diff --git a/docs/xplat/src/content/en/components/layouts/accordion.mdx b/docs/xplat/src/content/en/components/layouts/accordion.mdx index 48428e420d..b63de9f26e 100644 --- a/docs/xplat/src/content/en/components/layouts/accordion.mdx +++ b/docs/xplat/src/content/en/components/layouts/accordion.mdx @@ -1,92 +1,169 @@ --- -title: "{Platform} Accordion | Accordion | Infragistics" -description: Accordion is used to build vertical expandable panels in accordion menu. -keywords: "{Platform} Accordion, {ProductName}, Infragistics" +title: "{Platform} Accordion Component | Layouts | Infragistics" +description: "{Platform} Accordion is a layout component for organizing expandable and collapsible content panels in a vertical container." +keywords: "{Platform} Accordion, accordion component, expandable panels, {ProductName}, Infragistics" license: MIT -mentionedTypes: ["Accordion", "Infragistics.Controls.Layouts.Implementation.ExpansionPanel"] +last_updated: "2026-07-30" +mentionedTypes: ["Accordion", "ExpansionPanel"] namespace: Infragistics.Controls +relatedComponents: ["ExpansionPanel"] llms: - description: "The {ProductName} Accordion is a GUI component for building vertical expandable panels with clickable headers and associated content sections, displayed in a single container." + description: "The {ProductName} Accordion helps developers group related content into expandable and collapsible panels inside a vertical layout." --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import { Image } from 'astro:assets'; +import accordionAnatomy from '@xplat-images/anatomy-frame-light/Accordion-lt.png'; +import accordionDo from '@xplat-images/accordion/accordion_do1.png'; +import accordionDo2x from '@xplat-images/accordion/accordion_do1@2x.png'; +import accordionDoNot from '@xplat-images/accordion/accordion_do_not1.png'; +import accordionDoNot2x from '@xplat-images/accordion/accordion_dont1@2x.png'; +# Accordion Component +The {ProductName} Accordion is a layout component for organizing expandable content panels in a single vertical container. -# {Platform} Accordion Overview +## Live Demo -The {ProductName} 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. + -## {Platform} Accordion Example + -The following is a basic {ProductName} 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 accordion and its expansion panels. The sample also demonstrates the two types of expansion behavior. The switch button sets the property to toggle between single and multiple branches to be expanded at a time. + - + -## Getting Started with {Platform} Accordion +## Anatomy + +The accordion structure consists of an accordion container with one or more expansion panel children. + + + +1. Header: displays the section title and description and can be clicked to reveal or hide the panel's content
+2. Icon: indicates if the panel is open or closed. Could be placed on the left or on the right side of the header
+3. Panel: the section of content linked to an accordion header + + + + + +```text +igc-accordion // host - manages a set of expansion panels +└─ igc-expansion-panel // child panel + ├─ [slot="title"] // panel header title + ├─ [slot="subtitle"] // optional header subtitle + ├─ [slot="indicator"] // custom collapsed/default indicator + ├─ [slot="indicator-expanded"] // optional custom expanded-state indicator + └─ default slot // expandable panel content +``` - + -First, you need to install the {ProductName} by running the following command: + -```cmd -npm install {PackageWebComponents} +```text +igx-accordion // host - manages a set of expansion panels +└─ igx-expansion-panel // child panel + ├─ igx-expansion-panel-header // panel header container + │ ├─ igx-expansion-panel-title // panel header title + │ ├─ igx-expansion-panel-description // optional header description + │ └─ igx-expansion-panel-icon // optional custom expand/collapse icon + └─ igx-expansion-panel-body // expandable panel content ``` -Before using the , you need to register it as follows: + -```ts -import { defineComponents, IgcAccordionComponent } from 'igniteui-webcomponents'; +## Getting Started -defineComponents(IgcAccordionComponent); -``` +### Prerequisites and Version Compatibility + + -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.mdx) topic. +Use the accordion with the {ProductName} version installed in your Angular application. Complete the shared [Getting Started](../general/getting-started.mdx) topic before importing the standalone accordion directives. - + + +Use the accordion with the {ProductName} version installed in your application. Complete the shared [Getting Started](../general-getting-started.mdx) topic before adding framework-specific imports or registration. -First, you need to the install the corresponding {ProductName} npm package by running the following command: + + + + +Import the standalone accordion directives before you use the component. If you have not set up {ProductName} yet, complete the shared [Getting Started](../general/getting-started.mdx) topic first. -```cmd -npm install igniteui-react +```ts +import { Component } from '@angular/core'; +import { IGX_ACCORDION_DIRECTIVES } from 'igniteui-angular/accordion'; + +@Component({ + selector: 'app-accordion', + imports: [IGX_ACCORDION_DIRECTIVES], + templateUrl: './accordion.component.html', +}) +export class AccordionComponent {} ``` -You will then need to import the and the and its necessary CSS, like so: + -```tsx + + +Register the accordion and expansion panel components before you use them. If you have not set up {ProductName} yet, complete the shared [Getting Started](../general-getting-started.mdx) topic first. + +```ts import { - IgrAccordion, - IgrExpansionPanel, -} from "igniteui-react"; -import "igniteui-webcomponents/themes/light/bootstrap.css"; + defineComponents, + IgcAccordionComponent, + IgcExpansionPanelComponent, +} from 'igniteui-webcomponents'; +defineComponents(IgcAccordionComponent, IgcExpansionPanelComponent); ``` -Before using the , you need to register it as follows: - - + -```csharp -// in Program.cs file +Import the React wrappers and the theme stylesheet before you render the accordion. If you have not set up {ProductName} yet, complete the shared [Getting Started](../general-getting-started.mdx) topic first. -builder.Services.AddIgniteUIBlazor(typeof(IgbAccordionModule)); +```tsx +import { IgrAccordion, IgrExpansionPanel } from 'igniteui-react'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; ``` -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Register the accordion module in `Program.cs` and add the theme stylesheet to your host page. If you have not set up {ProductName} yet, complete the shared [Getting Started](../general-getting-started.mdx) topic first. + +```csharp +builder.Services.AddIgniteUIBlazor(typeof(IgbAccordionModule)); +``` ```razor @@ -94,129 +171,750 @@ You will also need to link an additional CSS file to apply the styling to the -Now you can start with a basic configuration of the and its panels. - ## Usage -Each section in the {Platform} Accordion Component is defined using an {Platform} Expansion Panel. -Panels provide and properties, which give you the ability to configure the states of the panel as per your requirement. +Build the accordion by placing one or more components inside an container. + +### Single Expansion -### Declaring an Accordion + -The accordion wraps all expansion panels declared inside it. +Set to switch between one-open-panel behavior and multiple-open-panel behavior. + + + + + +Set to switch between one-open-panel behavior and multiple-open-panel behavior. + + + + + +```html + + + + Title Panel 1 + + +

Content Panel 1

+ + + + + Title Panel 2 + + +

Content Panel 2

+ + + +``` + + ```html - - - Title Panel 1 -

Content Panel 1

- - - Title Panel 2 -

Content Panel 2

- + + + Title Panel 1 +

Content Panel 1

+ + + Title Panel 2 +

Content Panel 2

+ ``` + + +```tsx + + + Title Panel 1 +

Content Panel 1

+ + + Title Panel 2 +

Content Panel 2

+ + +``` + + + ```razor - + + Title Panel 1 +

Content Panel 1

+ + + Title Panel 2 +

Content Panel 2

+ + +``` + + + +### Programmatic Expansion + + + +Use and to collapse or expand the accordion panels programmatically. + + +Calling expands only the last enabled panel when is `true`. + + + + + + +Use and to collapse or expand all available panels programmatically. + + +Calling expands all panels, even when is `true`. + + + + + + +```html + + + + + + + Title Panel 1 + + +

Content Panel 1

+ + + + + Title Panel 2 + + +

Content Panel 2

+ + + +``` + + + + + +```html + + + + + + Title Panel 1 +

Content Panel 1

+ + + Title Panel 2 +

Content Panel 2

+ + +``` + +```ts +const accordion = document.getElementById('accordion') as IgcAccordionComponent; + +document.getElementById('show-all').addEventListener('click', () => accordion.showAll()); +document.getElementById('hide-all').addEventListener('click', () => accordion.hideAll()); +``` + + + + + +```tsx +const accordionRef = useRef(null); + +return ( + <> + accordionRef.current?.showAll()}>Show All + accordionRef.current?.hideAll()}>Hide All + + + Title Panel 1

Content Panel 1

- - + + Title Panel 2

Content Panel 2

- - + + + +); ``` - + -```tsx - - +```razor +Show All +Hide All + + + Title Panel 1

Content Panel 1

- - + + Title Panel 2

Content Panel 2

+ + + +@code { + private IgbAccordion accordion; + + private async Task ShowAll() => await accordion.ShowAllAsync(); + + private async Task HideAll() => await accordion.HideAllAsync(); +} +``` + + + + + + + + + + + + + + + +### Customize Panel Content + + + +Customize panel headers with title and description elements, and place expandable content inside the panel body. + +```html + + + + Billing + Payment and invoice settings + + +

Update payment methods, billing contacts, and invoice delivery options.

+ + + +``` + + + + + +Customize the panel headers and content through the underlying slots. + + + + + +```html + + + Billing + Payment and invoice settings +

Update payment methods, billing contacts, and invoice delivery options.

+ + +``` + + + + + +```tsx + + + Billing + Payment and invoice settings +

Update payment methods, billing contacts, and invoice delivery options.

 ``` + + +```razor + + + Billing + Payment and invoice settings +

Update payment methods, billing contacts, and invoice delivery options.

+ + +``` + + + + + + + + + + + + + + + +### Nest Accordions + + + +Nest an accordion inside an expansion panel body when you need a second level of grouped disclosure. + +```html + + + + Account Settings + + + + + + Notifications + + +

Configure email and product notification preferences.

+ + + + + + +``` + + + + + +Nest an accordion inside an expansion panel when you need a second level of grouped disclosure. + + + -Using the accessor you can get a reference to the collection containing all expansion panels children of the . +```html + + + Workspace Settings + + + Notifications +

Configure email and product notification preferences.

+ + + + +``` + + + + + +```tsx + + + Workspace Settings + + + Notifications +

Configure email and product notification preferences.

+ + + + +``` + + + + + +```razor + + + Workspace Settings + + + Notifications +

Configure email and product notification preferences.

+ + + + +``` + + + + + + + + + + + + + + + +### Do/Don't + +**When to use:** Use the accordion when you need to organize secondary content, FAQ entries, settings groups, or other related vertical sections that users expand on demand. Keep panel titles short and descriptive, and enable single-expansion behavior when users should focus on one section at a time. + + + +**When not to use:** Use the [Expansion Panel](../expansion-panel.mdx) when you need a single standalone expandable section instead of a coordinated container that manages multiple panels together. Do not use an accordion to hide essential primary content or to group unrelated sections. + + + + + +**When not to use:** Use the [Expansion Panel](./expansion-panel.mdx) when you need a single standalone expandable section instead of a coordinated container that manages multiple panels together. Do not use an accordion to hide essential primary content or to group unrelated sections. + + + +
+ + + + + + + + + + + + + +
DoDon't
{Platform} Accordion do guidance{Platform} Accordion don't guidance
+
+ +## Properties + + + +The accordion exposes container-level controls; panel-specific state is configured on each . + +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| | `boolean` | `false` | Controls whether one or multiple panels can stay expanded at the same time. | +| | `QueryList` | n/a | Returns the collection of child expansion panels in the accordion. | + + + + + +The accordion exposes a small set of container-level controls; panel-specific state is configured on each . + +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| | `boolean` | `false` | Controls whether one or multiple panels can stay expanded at the same time. | +| | | n/a | Returns the collection of child expansion panels in the accordion. | + + + +## Methods + + + +Use the accordion methods when you need to change panel state from your code. + +| Name | Description | +| -- | -- | +| | Expands the available panels. | +| | Collapses the available panels. | + + + + -```typescript -private accordion: IgcAccordionComponent; -private panels: IgcExpansionPanelComponent[]; +Use the accordion methods when you need to change panel state from your code. -constructor() { - this.accordion = document.getElementById("accordion") as IgcAccordionComponent; - this.panels = this.accordion.panels; +| Name | Description | +| -- | -- | +| | Expands all available panels. | +| | Collapses the available panels. | + + + +## Styling + + + +Style the {Platform} accordion with CSS parts and Ignite UI theme variables. + + + + + + + + + + + + + + + + + +### Sass Theming + +Use the function to create a custom expansion panel theme, then include the generated tokens in the component stylesheet. + +```scss +@use "igniteui-angular/theming" as *; + +$custom-panel-theme: expansion-panel-theme( + $header-background: #011627, + $body-background: #f0ece7, + $expanded-margin: 10px +); + +:host { + @include tokens($custom-panel-theme); } ``` +### Styling Variables + +| Variable | What it changes | +| -- | -- | +| `$header-background` | The panel header background color. | +| `$header-focus-background` | The panel header background color when focused. | +| `$header-title-color` | The panel header title text color. | +| `$header-description-color` | The panel header description text color. | +| `$header-icon-color` | The panel header icon color. | +| `$body-background` | The panel body background color. | +| `$body-color` | The panel body text color. | +| `$expanded-margin` | The margin applied to expanded panels when they are placed inside an accordion. | +| `$border-radius` | The expansion panel border radius. | + -As demonstrated above, the property gives you the ability to set whether single or multiple panels can be expanded at a time. +### Styling with Tailwind -By using the and methods you can respectively collapse and expand all s of the programmatically. + - -If property is set to **true** calling method would expand only the focused panel. - +Use Tailwind utility classes with CSS part selectors when you want to keep the styling close to the component markup. + + + + -### {Platform} Accordion Customization Example + -With the {Platform} Accordion, 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 slots of the . + - +Style the accordion by targeting the parts exposed by its child components. -### Nested {Platform} Accordions Scenario +### Styling Variables -In the following {Platform} Accordion example is created a complex FAQ section in order to illustrate how you can go about this common application scenario. In the sample nested is achieved by adding an accordion inside an expansion panel. +Use {ProductName} theme CSS variables as values when styling the expansion panel parts. - +| Variable | What it changes | +| -- | -- | +| `--ig-secondary-900` | Supplies the dark background color used by the panel and header in the example below. | +| `--ig-secondary-900-contrast` | Supplies a readable foreground color for content on `--ig-secondary-900`. | +| `--ig-warn-500` | Supplies the accent color used by the indicator, title, and subtitle in the example below. | -## Keyboard Navigation +```css +igc-expansion-panel { + background-color: var(--ig-secondary-900); + color: var(--ig-secondary-900-contrast); +} + +igc-expansion-panel::part(header) { + background-color: var(--ig-secondary-900); +} + +igc-expansion-panel::part(indicator), +igc-expansion-panel::part(title), +igc-expansion-panel::part(subtitle) { + color: var(--ig-warn-500); +} +``` + +### CSS Parts + +| Part | What it changes | +| -- | -- | +| `header` | The container for the expansion indicator, title, and subtitle. | +| `title` | The title container. | +| `subtitle` | The subtitle container. | +| `indicator` | The indicator container. | +| `content` | The expansion panel content wrapper. | + + -Keyboard navigation in the {Platform} 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. +## Accessibility -The Accordion navigation is compliant with W3C accessibility standards and convenient to use. +The accordion supports keyboard interaction for moving focus between panels and changing their expanded state. -**Key Combinations** -- ↓ - moves the focus to the panel below -- ↑ - moves the focus to the panel above -- ALT + ↓ - opens the focused panel in the accordion -- ALT + ↑ - closes the focused panel in the accordion -- SHIFT + ALT + ↓ - opens all enabled panels (if singleExpand is set to true opens the focused panel) -- SHIFT + ALT + ↑ - closes all enabled panels -- HOME - navigates to the FIRST enabled panel in the accordion -- END - navigates to the LAST enabled panel in the accordion +### Keyboard Interaction - + +Use the keyboard shortcuts below to move through the accordion and open or close panels. + +| Key | Action | +| -- | -- | +| Down Arrow | Moves focus to the panel below. | +| Up Arrow | Moves focus to the panel above. | +| Alt + Down Arrow | Opens the focused panel. | +| Alt + Up Arrow | Closes the focused panel. | +| Shift + Alt + Down Arrow | Opens all enabled panels. If is `true`, opens the last enabled panel. | +| Shift + Alt + Up Arrow | Closes all enabled panels. | +| Home | Moves focus to the first enabled panel. | +| End | Moves focus to the last enabled panel. | + + + + + +Use the keyboard shortcuts below to move through the accordion and open or close panels. + +| Key | Action | +| -- | -- | +| Down Arrow | Moves focus to the panel below. | +| Up Arrow | Moves focus to the panel above. | +| Alt + Down Arrow | Opens the focused panel. | +| Alt + Up Arrow | Closes the focused panel. | +| Shift + Alt + Down Arrow | Opens all enabled panels. If is `true`, opens only the focused panel. | +| Shift + Alt + Up Arrow | Closes all enabled panels. | +| Home | Moves focus to the first enabled panel. | +| End | Moves focus to the last enabled panel. | + + + +### Screen Readers / ARIA + +The accordion's accessibility semantics are provided through its child expansion panels and their headers. + +- Each panel header exposes `role="button"`, `aria-expanded`, and `aria-controls`. +- Each panel body exposes `role="region"` and a label through `aria-labelledby` or `aria-label`. +- Use clear title text for each panel so assistive technologies can announce a meaningful label. +- Keep interactive content inside panel bodies in a logical tab order. + +### Accessibility Compliance + + + +Infragistics documents {ProductName} accessibility support for Section 508 and WCAG 2.1 guideline areas in the [Accessibility Compliance](../interactivity/accessibility-compliance.mdx) topic. The accordion's compliance evidence comes from the child components that provide the interactive headers and regions. + + + + + +Infragistics documents {ProductName} accessibility support for Section 508 and WCAG 2.1 guideline areas in the [Accessibility Compliance](../interactivity/accessibility-compliance.mdx) topic. The accordion's compliance evidence comes from the child components that provide the interactive headers and regions. + + + +| Criterion | How the component complies | +| -- | -- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) | The accordion supports keyboard commands for moving focus and opening or closing panels. | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order) | Focus moves through enabled panels in sequence, with shortcuts for jumping to the first and last panel. | + +Your responsibilities: + +- Provide panel titles that describe the content behind each disclosure area. +- Preserve a logical focus order in the surrounding page layout. +- Validate any custom styling against your application's contrast and focus-indicator requirements. ## API References + + +## Dependencies + +The accordion depends on for its visible sections. + + + +The accordion also depends on the shared theme stylesheet for its default appearance. + + + ## Additional Resources +Use these resources to continue with {ProductName} Accordion support, source, and related layout guidance. + - [{ProductName} **Forums**]({ForumsLink}) - [{ProductName} **GitHub**]({GithubLink}) + +## Related Components + + + +Use the [Expansion Panel](../expansion-panel.mdx) when you need a single expandable section instead of a container that coordinates multiple panels. + + + + + +Use the [Expansion Panel](./expansion-panel.mdx) when you need a single expandable section instead of a container that coordinates multiple panels. + + + +## FAQ + + + + Allow multiple panels to stay open when users need to compare or cross-reference their content. Use single-expansion behavior when the workflow is clearer with one active section at a time. + + + Avoid using an accordion for essential, long, or comparison-heavy content that users need to read at once. Use clear headings, a separate page, or another layout when hiding the content would make it harder to find or compare. + + + Use short, descriptive headers that clearly identify the content revealed by each panel. Users should be able to scan the headers and decide which section to open. + + + Avoid placing other interactive controls inside an accordion header. Keep secondary actions outside the header so the panel trigger remains clear and does not contain nested interactive elements. + + diff --git a/docs/xplat/src/content/en/toc.json b/docs/xplat/src/content/en/toc.json index 5839d7ff38..501ea05c8f 100644 --- a/docs/xplat/src/content/en/toc.json +++ b/docs/xplat/src/content/en/toc.json @@ -2215,11 +2215,10 @@ "header": true }, { - "exclude": [ - "Angular" - ], + "exclude": [], "name": "Accordion", - "href": "layouts/accordion.mdx" + "href": "layouts/accordion.mdx", + "updated": true }, { "name": "Avatar",