skip to content

Headless Widget Primitives

Angular Aria's directives and the CDK menu, listbox, tree and stepper bring keyboard, focus and ARIA behaviour with no styling. Interviewers ask when to build on them instead of on Material.

part ofAngular Material & CDKread it →
on this pageshow

explore

questions

6

In Angular Aria, what does adding `ngListbox` and `ngOption` to your own elements give you, and what is still left for you to build?

level: middleimportance: must knowfreq 32%

answer

  1. behaviour without a single style rule
  2. roles and ARIA states on your elements
  3. arrow keys, Home, End, typeahead
  4. value is a model holding an array
  5. selectionMode defaults to follow

basics

~20 s

Angular Aria's ngListbox and ngOption add the WAI-ARIA listbox pattern to elements you write: roles and ARIA states, arrow-key and typeahead navigation, focus management and selection in a value array. Markup, styles, data and filtering stay yours.

solid answer

~40 s

`ngListbox` (from `@angular/aria/listbox`) puts `role="listbox"`, `aria-multiselectable`, `aria-orientation` and `aria-activedescendant` on its host, and each `ngOption` gets `role="option"`, `aria-selected`, `aria-disabled` and a `data-active` attribute. It handles arrow keys, Home and End, typeahead, wrapping, right-to-left reversal, and either roving `tabindex` or active-descendant focus. Selection lives in a `value` model that is always an array, even with `multi` off, so you bind `[(value)]` to a signal. Two defaults surprise people: `selectionMode` is `'follow'`, so arrowing selects, and `softDisabled` is `true`, so disabled options still take focus. It draws nothing: you write the elements, style them from `aria-selected` and `data-active`, supply the options, and wrap it yourself if a form must read it.

code

html · 5 lines
html
<ul ngListbox aria-label="Insert block" [multi]="true" focusMode="activedescendant" [(value)]="blocks">
  <li ngOption value="table">Table</li>
  <li ngOption value="image">Image</li>
  <li ngOption value="code" [disabled]="true">Code block</li>
</ul>

go deeper

for a junior

Remember the split: Angular Aria brings roles, keyboard handling and focus; you bring the HTML and every line of CSS.

for a middle

Explain the defaults precisely: value is an array model, selectionMode follow selects on focus, softDisabled keeps disabled options focusable, and focusMode picks roving tabindex or aria-activedescendant.

for a senior

Show you can style from aria-selected and data-active, choose explicit selection where focus-driven selection would cause side effects, and wrap the directive when a form must own the value.

for a principal

Frame the listbox as the unit your kit's select, autocomplete and pickers compose from, and weigh its recent 22.0.0 renames against the cost of owning that keyboard logic yourself.

## What Angular Aria is **Angular Aria** (`@angular/aria`) is a set of **headless directives** published from the same repository as Angular Material and the CDK. Each directive implements one WAI-ARIA Authoring Practices pattern (listbox, combobox, menu, menubar, tabs, tree, grid, toolbar, accordion) on elements *you* write. Its developer-preview tag was removed in **22.0.0**, so in v22 it is a stable package with a peer dependency on `@angular/cdk`. "Headless" here is literal: the package ships no CSS at all. What it ships is behaviour and semantics. The listbox is the smallest example: `ngListbox` goes on a container and `ngOption` on each child. Both are standalone directives, imported as `Listbox` and `Option` from `@angular/aria/listbox`. ## What the directives put on your elements | Element | Attributes the directive manages | |---|---| | `ngListbox` host | `role="listbox"`, `aria-multiselectable`, `aria-orientation`, `aria-disabled`, `aria-readonly`, `aria-activedescendant`, `tabindex` | | each `ngOption` | `role="option"`, `aria-selected`, `aria-disabled`, `id`, `tabindex`, `data-active` | Those attributes are also your **styling hooks**. A selected option is `[aria-selected='true']`, the keyboard-active one is `[data-active='true']`, and a disabled one is `[aria-disabled='true']`. Styling from state attributes keeps the visuals and the accessibility tree in step, because both read the same source. ## Keyboard, focus and selection The listbox handles the keyboard for you: - **Arrow keys** move the active option (Up and Down, or Left and Right with `orientation="horizontal"`, reversed under right-to-left text). - **Home and End** jump to the first and last option. - **Typeahead** jumps to the option whose label starts with the typed characters; `[label]` on `ngOption` overrides the text it matches. - **Space and Enter** select in `explicit` mode; with `multi`, Shift plus an arrow extends a range and Ctrl or Cmd plus A toggles all. - **`wrap`** (default `true`) lets navigation loop from the last option to the first. The inputs that change behaviour, with their v22 defaults: | Input | Default | Effect | |---|---|---| | `multi` | `false` | allow several selected options | | `selectionMode` | `'follow'` | `'follow'` selects whatever gets focus; `'explicit'` waits for Space or Enter | | `focusMode` | `'roving'` | `'roving'` moves DOM focus to options; `'activedescendant'` keeps focus on the listbox and points `aria-activedescendant` at the active option | | `softDisabled` | `true` | disabled options stay focusable but cannot be selected; `false` skips them | | `value` | `[]` | a **model** of the selected values | The `value` model is always an **array**, even for a single-select listbox, where it holds zero or one item. In 22.0.0 this model was renamed from `values` to `value`, so older templates binding `[(values)]` no longer compile. In development builds the listbox also prints console warnings when a single-select listbox holds more than one value, or when two options share a value or an id. ## What stays yours 1. **The markup.** You choose the elements, their order and their content. 2. **Every style.** No colours, spacing, check marks or focus rings arrive with the directive. 3. **The data and any filtering.** The listbox renders the options you give it; narrowing them is a signal in your component. 4. **Forms integration.** The directive exposes a `value` model, not a form control; to bind it to a form, wrap it in a component that implements Angular's form-control contract. 5. **Positioning** when it lives in a popup. Inside a combobox, the angular.dev examples position the popup with the CDK's connected overlay. ## Example: a paragraph-style picker A document editor's sidebar offers paragraph styles. `explicit` mode stops arrowing from restyling the paragraph on every keypress: ```ts import {Component, signal} from '@angular/core'; import {Listbox, Option} from '@angular/aria/listbox'; @Component({ selector: 'app-paragraph-style', imports: [Listbox, Option], template: ` <ul ngListbox aria-label="Paragraph style" selectionMode="explicit" [(value)]="style"> @for (s of styles; track s.id) { <li ngOption [value]="s.id" [label]="s.name">{{ s.name }}</li> } </ul> `, styles: ` [ngOption][data-active='true'] { outline: 2px solid currentColor; } [ngOption][aria-selected='true'] { font-weight: 600; } `, }) export class ParagraphStyle { readonly styles = [ {id: 'p', name: 'Normal text'}, {id: 'h1', name: 'Heading 1'}, {id: 'quote', name: 'Quote'}, ]; readonly style = signal<string[]>(['p']); } ``` ## Mistakes to avoid - Expecting a single value from a single-select listbox: read `style()[0]`. - Forgetting that `follow` is the default, then wondering why focus changes the selection. - Confusing `ngListbox` with the CDK's `cdkListbox`: different package, different inputs (`cdkListboxValue`, `cdkListboxMultiple`), and the CDK one also acts as a form control.

  • How does `focusMode` change what happens to DOM focus in an Angular Aria listbox?
    With `'roving'`, the default, the active option gets `tabindex="0"` and real DOM focus while the others get `-1`. With `'activedescendant'`, focus stays on the `ngListbox` element and `aria-activedescendant` names the active option's id, so a screen reader announces it without focus moving. You need the second mode when focus must stay somewhere else, such as a combobox's text input.
  • What does Angular Aria's listbox warn you about in a development build?
    After rendering, it checks the pattern and prints `console.warn` messages: a single-select listbox whose `value` holds more than one item, two options with the same value, or two options with the same id. These are warnings, not thrown errors, and the check runs only in dev mode, so treat them as bugs to fix before release.

  • ngListbox ships default styles that you override with CSS variables
  • A single-select ngListbox holds one value, not an array
  • Arrow keys only move focus; selection always needs Space or Enter
  • Disabled ngOption elements are always skipped by the keyboard
  • ngListbox plugs straight into formControlName like a native select
  • ngListbox and cdkListbox are the same directive under two names

Assumes Angular Aria 22, stable since 22.0.0, which also renamed the listbox's values model to value.

open as a page

In Angular Aria 22, a document editor's mention picker built from `ngCombobox` and an `ngListbox` popup lists every user whatever is typed and renders inline; why, and what fixes it?

level: seniorimportance: should knowfreq 24%

basics

~20 s

Angular Aria's combobox only coordinates an input with its popup: ARIA states, expansion and keyboard forwarding. It neither filters nor positions. Filter options with a computed signal over the combobox's text value, and place the popup with the CDK's connected overlay.

open as a page

A publish wizard built by extending the Angular CDK's `CdkStepper` fails with 'No provider found for CdkStepper' from its `<cdk-step>` children; why, and what else must the subclass supply?

level: seniorimportance: should knowfreq 28%

basics

~20 s

CdkStep and the cdkStepperNext and cdkStepperPrevious buttons inject CdkStepper, but a subclass component is registered under its own class. Provide CdkStepper with useExisting pointing at the subclass, then supply the template: step content, headers, navigation and ARIA.

open as a page

After moving a document editor's Angular CDK `cdk-tree` file explorer from `treeControl` to `childrenAccessor`, folders open by toggle click but not Right Arrow and lose `aria-expanded`; why?

level: seniorimportance: should knowfreq 26%

basics

~20 s

Without a treeControl, a cdk-tree-node is expandable only when its isExpandable input says so, and it defaults to false. Keyboard expansion and aria-expanded honour that flag, while cdkTreeNodeToggle calls the tree directly. Bind isExpandable on every folder node.

open as a page

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%

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.

open as a page

In an Angular CDK menu bar, why does a `cdkMenuItemCheckbox` for 'Show ruler' come back unchecked each time its View menu reopens, and how do you fix it?

level: middleimportance: nice to knowfreq 22%

basics

~20 s

A CDK pop-up menu is an ng-template rendered into an overlay on open and destroyed on close, so a checkbox item's internal toggle is lost. Keep the state in the component: bind cdkMenuItemChecked and update it from cdkMenuItemTriggered.

open as a page