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?
answer
- the default axis
- horizontal is opt-in
- direction flips the arrows
- builder calls chain
- forward every keydown
basics
~20 sA 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 linesimport {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
Remember that a CDK list key manager is vertical by default and that horizontal arrows need withHorizontalOrientation.
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.
Cover right-to-left handling through Directionality and its change stream, typeahead's getLabel requirement, and cleaning up with destroy().
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.