skip to content

For a document editor's in-house Angular component kit, how do you decide per widget between Angular Aria, the Angular CDK primitives and Angular Material 22?

level: principalimportance: should knowfreq 18%

answer

  1. three layers, one repository
  2. look owned versus behaviour owned
  3. who positions the popup
  4. which layer sets the ARIA
  5. stable, but renamed in 22.0.0

basics

~20 s

Pick per widget by who owns the look and which layer fully implements the pattern: Material if its Material 3 look is acceptable, a CDK primitive if it ships the needed roles, Angular Aria for complete ARIA patterns on your markup.

solid answer

~50 s

Angular Material gives styled Material 3 widgets you adjust through its theme and tokens; several sit on CDK classes (`mat-stepper` extends `CdkStepper`, `mat-tree` extends `CdkTree`, the expansion panel extends `CdkAccordion`), so their behaviour matches the CDK's. The CDK primitives give behaviour with your markup, but unevenly: `cdkMenu`, `cdkListbox` and `cdk-tree` set roles and keyboard handling, and the CDK menu even owns its overlay, while `CdkAccordion` and `CdkStepper` leave ARIA to you. Angular Aria gives complete WAI-ARIA patterns, including toolbar, grid, tabs and accordion, as signal-based directives on your markup, but you bring positioning, filtering and forms wrapping, and it only became stable in 22.0.0, a release that still renamed its `values` model and replaced its combobox. For the editor: Aria for the formatting toolbar and mention picker, the CDK tree for the file explorer, `CdkStepper` or `mat-stepper` for the publish wizard, and one wrapper per widget.

go deeper

for a junior

Name the three layers and what each hands you: finished components, behaviour primitives, or ARIA patterns on your own markup.

for a middle

Explain where the CDK primitives differ, for example the menu and listbox setting roles while the accordion and stepper leave ARIA to you.

for a senior

Map each editor widget to a layer from concrete gaps such as overlay ownership, missing patterns and forms integration, and wrap each choice in the kit.

for a principal

Own the trade-off across the kit: consistency of one layer versus best fit per widget, Angular Aria's recent API churn, and the migration cost if a choice changes later.

## The three layers All three packages are published from the angular/components repository and version-locked to Angular. | Layer | Package | You get | You own | |---|---|---|---| | **Angular Material** | `@angular/material` | styled Material 3 components, themed through `mat.theme` and system tokens | the parts the theme API exposes; internal DOM is private | | **CDK primitives** | `@angular/cdk/menu`, `/listbox`, `/tree`, `/stepper`, `/accordion` | behaviour, and for some of them roles and keyboard handling | markup, styles, and the ARIA the primitive leaves out | | **Angular Aria** | `@angular/aria` | the full WAI-ARIA pattern (roles, states, keyboard, focus) as directives on your elements | markup, styles, data, popup positioning, form integration | Angular Aria declares `@angular/cdk` as a peer dependency, and its own guide steers teams that want components that look finished toward Angular Material, which is a fair summary of the trade. ## The CDK is not uniformly accessible The CDK primitives differ more than their shared prefix suggests: - **`cdkMenuBar`, `cdkMenu`, `cdkMenuItem`** set `menubar`, `menu`, `menuitem`, `menuitemcheckbox` and `menuitemradio` roles, handle the keyboard, and open pop-up menus in an overlay themselves. - **`cdkListbox` and `cdkOption`** set listbox roles and states and also act as a form control. - **`cdk-tree`** sets tree roles, levels and `aria-expanded`; its guide ties the full treatment to `childrenAccessor` or `levelAccessor`, with `isExpandable` bound on nodes. - **`CdkAccordion`** manages expansion state only. Its guide says it applies no accessibility treatment: you add `role="button"`, `aria-expanded`, `aria-controls` and `role="region"` yourself. - **`CdkStepper`** manages selection and validation; apart from keyboard handling it applies no treatment beyond `cdkStepHeader`'s `role="tab"`. Angular Aria fills exactly those gaps: `ngAccordionTrigger` sets `role="button"`, `aria-expanded` and `aria-controls`, and `ngAccordionPanel` sets `role="region"` and `aria-labelledby`. It also covers patterns the CDK has no primitive for, such as **toolbar** (`ngToolbar`), **grid** (`ngGrid`) and **tabs** (`ngTabs`). It has no stepper. ## Material's own gaps Material offers a styled `mat-menu`, but **no menubar**, and `mat-menu` is not built on the CDK menu package. `mat-toolbar` is a container for headers, titles and actions, not the keyboard toolbar pattern. Material's autocomplete is a Material-styled panel attached to a text input, usually inside its form field. When the brand look must differ substantially from Material 3, theming stops at what the token and overrides APIs expose. ## A per-widget decision for the editor | Widget | Likely choice | Why | |---|---|---| | Formatting toolbar | Angular Aria `ngToolbar` | the toolbar keyboard pattern exists only here | | Menu bar (File, Edit, View) | CDK `cdkMenuBar`, or Aria `ngMenuBar` | the CDK positions submenus for you; Aria needs a connected overlay per menu | | Mention picker | Aria `ngCombobox` plus `ngListbox` | a combobox primitive; filtering and positioning are yours either way | | File explorer | CDK `cdk-tree` or Aria `ngTree` | data-driven node templates versus hand-written markup | | Publish wizard | `mat-stepper` or a `CdkStepper` subclass | Aria has no stepper; Material if its look is acceptable | | Settings sections | Aria accordion | the CDK accordion would leave all ARIA to you | ## How to decide 1. **List the widgets** and, for each, the WAI-ARIA pattern it must satisfy. 2. **Ask who owns the look.** If Material 3 with your theme is acceptable, Material wins on cost. 3. **Check which layer implements the pattern completely**, using the gaps above rather than package names. 4. **Count the glue you inherit**: popups to position, filters to write, form wrappers to build. 5. **Wrap each choice once** in the kit so product teams never touch the primitive directly, and so a later switch is local. ## Costs and risks to weigh - **Maturity.** Angular Aria's developer-preview tag was removed in 22.0.0, the same release that renamed its `values` model to `value` and replaced its combobox. Budget for API movement. - **Mixed generations.** The CDK primitives mostly use decorator `@Input`s and `EventEmitter` outputs; Aria uses signal inputs and models throughout. A kit mixing both should hide the difference behind its own API. - **Forms.** `cdkListbox` is a form control out of the box; Aria directives expose models that you wrap for forms. - **Testing.** Material ships ready-made harnesses, and Angular Aria's guides show harnesses for its directives too; a CDK-based widget usually needs your own. There is no single right answer. A kit that standardises on Aria for consistency may still take `CdkStepper` for the wizard; one that standardises on Material may drop to Aria for the toolbar only.

  • What does choosing Angular Aria cost that the CDK primitives do not?
    Newer API surface: it became stable only in 22.0.0, which still renamed `values` to `value` and replaced the combobox. Its directives are not form controls, so each needs a wrapper for forms. Popups are positioned by you, typically with the CDK's connected overlay. In return you get complete ARIA patterns, including accordion, tabs, toolbar and grid, that the CDK either leaves bare or lacks.
  • When is Angular Material still the right base despite a custom brand?
    When the brand can be expressed through Material's theme and token overrides and the widget exists in Material. Because `mat-stepper`, `mat-tree` and the expansion panel extend CDK classes, you keep the same behaviour and gain finished visuals and ready-made test harnesses. It stops being right once the design needs DOM changes the private markup does not allow.

  • Angular Material's mat-menu is built on the CDK menu package
  • Angular Aria is still a developer preview in version 22
  • The CDK accordion applies aria-expanded and region roles for you
  • Angular Aria directives position their own popups
  • Angular Material offers a menubar component for desktop-style menus

Assumes Angular Material, CDK and Angular Aria 22; Angular Aria lost its developer-preview tag in 22.0.0.