skip to content

Why does a filter-chip toolbar built on the Angular CDK's `FocusKeyManager` ignore the Left and Right arrow keys, and which configuration fixes it?

level: middleimportance: should knowfreq 21%

answer

  1. the default axis
  2. horizontal is opt-in
  3. direction flips the arrows
  4. builder calls chain
  5. forward every keydown

basics

~20 s

A ListKeyManager such as FocusKeyManager handles only Up and Down by default; horizontal movement is off until withHorizontalOrientation('ltr' or 'rtl') is called. Chain withVerticalOrientation(false), withWrap() and withHomeAndEnd() as needed, and forward keydown events to onKeydown.

solid answer

~40 s

`ListKeyManager`, the base of `FocusKeyManager`, starts with vertical navigation on, horizontal navigation off (`null`), no wrapping, no Home/End, no Page Up/Down and no typeahead. A toolbar therefore needs `.withHorizontalOrientation(dir)`, where `dir` is `'ltr'` or `'rtl'` so the arrows follow reading direction, usually from the CDK's `Directionality`. Add `.withVerticalOrientation(false)` if Up and Down should not move, `.withWrap()` to loop at the ends and `.withHomeAndEnd()` for first and last. The manager only reacts to keys you pass it, so the host's `keydown` must call `keyManager.onKeydown(event)`. It does not manage `tabindex`; keep one chip at `tabindex="0"` and the rest at `-1` from its `change` stream.

code

ts · 21 lines
ts
import {Component, Injector, inject, viewChildren} from '@angular/core';
import {FocusKeyManager} from '@angular/cdk/a11y';
import {Directionality} from '@angular/cdk/bidi';
import {FilterChip} from './filter-chip';

@Component({
  selector: 'app-filter-toolbar',
  imports: [FilterChip],
  host: {role: 'toolbar', '(keydown)': 'keyManager.onKeydown($event)'},
  template: `@for (f of filters; track f) { <button appFilterChip>{{ f }}</button> }`,
})
export class FilterToolbar {
  filters = ['Size', 'Colour', 'Price'];
  private chips = viewChildren(FilterChip);

  keyManager = new FocusKeyManager(this.chips, inject(Injector))
    .withHorizontalOrientation(inject(Directionality).value)
    .withVerticalOrientation(false)
    .withWrap()
    .withHomeAndEnd();
}

go deeper

for a junior

Remember that a CDK list key manager is vertical by default and that horizontal arrows need withHorizontalOrientation.

for a middle

List the defaults and the builder calls that change them, and explain that keydown must be forwarded to onKeydown and tabindex kept by the component.

for a senior

Cover right-to-left handling through Directionality and its change stream, typeahead's getLabel requirement, and cleaning up with destroy().

for a principal

Discuss when a team should build on the key manager versus adopting a ready-made headless toolbar primitive, and what each leaves to maintain.

## What a key manager is The Angular CDK's `@angular/cdk/a11y` package contains **list key managers**: plain classes, not directives, that track which item of a list is *active* and change it in response to keyboard events. `ListKeyManager` is the base class; `FocusKeyManager` moves real DOM focus to the active item; `ActiveDescendantKeyManager` only re-styles it. Material's chip set, menu and selection list are built on these classes, and a custom widget such as a filter-chip toolbar uses them the same way. ## The defaults that cause the bug A freshly constructed manager is configured for a vertical list: | Setting | Default | Builder that changes it | |---|---|---| | Up / Down arrows | on | `withVerticalOrientation(false)` | | Left / Right arrows | off (`null`) | `withHorizontalOrientation('ltr' \| 'rtl')` | | Wrap at the ends | off | `withWrap()` | | Home / End | off | `withHomeAndEnd()` | | Page Up / Page Down | off | `withPageUpDown(true, delta)`, delta defaults to 10 | | Typeahead | off | `withTypeAhead(debounceMs)`, default 200 ms | | Items skipped | disabled ones | `skipPredicate(fn)` | | Modifier keys allowed with arrows | none | `withAllowedModifierKeys([...])` | With horizontal orientation `null`, `onKeydown` returns early for Left and Right without moving anything or calling `preventDefault`. That is exactly the reported symptom. ## The fix, step by step 1. **Turn on the horizontal axis** with `withHorizontalOrientation(direction)`. With `'rtl'` the manager swaps the meaning of the arrows, so Right moves to the previous item. Read the direction from the CDK `Directionality` service, and call the builder again when its `change` stream emits if the app can switch direction at runtime. 2. **Decide on the vertical axis.** A one-row toolbar often disables it with `withVerticalOrientation(false)`, so Up and Down keep their default behaviour. Material's own chip set leaves both axes on. 3. **Add the conveniences** the pattern expects: `withWrap()` and `withHomeAndEnd()`. 4. **Forward key events.** The manager never listens to the DOM. Bind the toolbar host's `keydown` and call `keyManager.onKeydown(event)`. It calls `preventDefault` only for keys it handled; Tab just emits on its `tabOut` stream. 5. **Manage `tabindex` yourself.** The manager does not touch attributes. Keep the active chip at `tabindex="0"` and the others at `-1`, updated from the `change` stream, so Tab enters the toolbar on the active chip. 6. **Destroy it.** Call `destroy()` when the component is destroyed to release its subscriptions. ## Items and inputs - Items passed to a `FocusKeyManager` implement `FocusableOption`: a `focus()` method, plus optional `disabled` and `getLabel()`. - The constructor accepts a `QueryList`, an array, or a signal of items; a signal, such as the result of `viewChildren()`, requires an `Injector` as the second argument. - `withTypeAhead()` requires every item to implement `getLabel()`; in development mode it throws if one does not. ## Why the defaults are vertical The managers were designed for `role="menu"` and `role="listbox"` lists, which are vertical by default. Toolbars, tab lists and chip rows are horizontal, so they opt in. Remembering that the axis is a **configuration**, not a detected layout, is what lets you diagnose this bug in seconds.

  • What happens if you enable withTypeAhead() on a FocusKeyManager whose items lack getLabel()?
    Typeahead matches typed characters against each item's `getLabel()` result. In development mode, `withTypeAhead()` throws an error saying items in typeahead mode must implement `getLabel`. Implement `getLabel()` on the item class, returning its visible text.
  • Why does Tab still leave the toolbar in one step after you wire the FocusKeyManager?
    The manager does not handle Tab beyond emitting on `tabOut`, and it never sets `tabindex`. If only the active chip has `tabindex="0"` and the rest `-1`, Tab moves out of the toolbar in one step, as a toolbar should; if every chip stays at `0`, Tab visits each chip.

  • FocusKeyManager detects a horizontal layout and enables Left and Right on its own.
  • Passing 'rtl' to withHorizontalOrientation has the same effect as 'ltr'.
  • The key manager listens to keydown events on the items by itself.
  • FocusKeyManager sets tabindex on the items to build a roving tab stop.
  • Wrapping from the last item to the first is on by default.