Accessibility • Angular Material

API reference for Angular CDK a11y

import {A11yModule} from '@angular/cdk/a11y';

`AriaDescriber`

Utility that creates visually hidden elements with a message content. Useful for elements that want to use aria-describedby to further describe themselves without adding additional visual content.

Methods

describe (hostElement: `Element`, message: `string`, role?: `string`): `void`
Adds to the host element an aria-describedby reference to a hidden element that contains the message. If the same message has already been registered, then it will reuse the created message element.
Parameters
hostElement `Element`
message `string`
role? `string`

describe (hostElement: `Element`, message: `HTMLElement`): `void`
Adds to the host element an aria-describedby reference to an already-existing message element.
Parameters
hostElement `Element`
message `HTMLElement`

removeDescription (hostElement: `Element`, message: `string \| HTMLElement`, role?: `string`): `void`
Parameters
hostElement `Element`
message `string \| HTMLElement`
role? `string`

`InputModalityDetector`

Service that detects the user's input modality.

This service does not update the input modality when a user navigates with a screen reader (e.g. linear navigation with VoiceOver, object navigation / browse mode with NVDA, virtual PC cursor mode with JAWS). This is in part due to technical limitations (i.e. keyboard events do not fire as expected in these modes) but is also arguably the correct behavior. Navigating with a screen reader is akin to visually scanning a page, and should not be interpreted as actual user input interaction.

When a user is not navigating but interacting with a screen reader, this service attempts to update the input modality to keyboard, but in general this service's behavior is largely undefined.

Properties

Name	Description
`modalityChanged: Observable<InputModality>`	Emits when the input modality changes.
`modalityDetected: Observable<InputModality>`	Emits whenever an input modality is detected.
`mostRecentModality: InputModality`	The most recently detected input modality.

`HighContrastModeDetector`

Service to determine whether the browser is currently in a high-contrast-mode environment.

Microsoft Windows supports an accessibility feature called "High Contrast Mode". This mode changes the appearance of all applications, including web applications, to dramatically increase contrast.

IE, Edge, and Firefox currently support this mode. Chrome does not support Windows High Contrast Mode. This service does not detect high-contrast mode as added by the Chrome "High Contrast" browser extension.

Methods

getHighContrastMode (): `HighContrastMode`
Gets the current high-contrast-mode for the page.
Returns
`HighContrastMode`

`ConfigurableFocusTrapFactory`

Factory that allows easy instantiation of configurable focus traps.

Methods

create (element: `HTMLElement`, config?: `ConfigurableFocusTrapConfig`): `ConfigurableFocusTrap`
Creates a focus-trapped region around the given element.
Parameters
element `HTMLElement`	The element around which focus will be trapped.
config? `ConfigurableFocusTrapConfig`	The focus trap configuration.
Returns
`ConfigurableFocusTrap`	The created focus trap instance.

`FocusTrapFactory`

Factory that allows easy instantiation of focus traps.

Methods

create (element: `HTMLElement`, deferCaptureElements: `boolean = false`): `FocusTrap`
Creates a focus-trapped region around the given element.
Parameters
element `HTMLElement`	The element around which focus will be trapped.
deferCaptureElements `boolean = false`	Defers the creation of focus-capturing elements to be done manually by the user.
Returns
`FocusTrap`	The created focus trap instance.

`InteractivityChecker`

Utility for checking the interactivity of an element, such as whether it is focusable or tabbable.

Methods

isDisabled (element: `HTMLElement`): `boolean`
Gets whether an element is disabled.
Parameters
element `HTMLElement`	Element to be checked.
Returns
`boolean`	Whether the element is disabled.

isFocusable (element: `HTMLElement`, config?: `IsFocusableConfig`): `boolean`
Gets whether an element can be focused by the user.
Parameters
element `HTMLElement`	Element to be checked.
config? `IsFocusableConfig`	The config object with options to customize this method's behavior
Returns
`boolean`	Whether the element is focusable.

isTabbable (element: `HTMLElement`): `boolean`
Gets whether an element can be reached via Tab key. Assumes that the element has already been checked with isFocusable.
Parameters
element `HTMLElement`	Element to be checked.
Returns
`boolean`	Whether the element is tabbable.

isVisible (element: `HTMLElement`): `boolean`
Gets whether an element is visible for the purposes of interactivity. This will capture states like `display: none` and `visibility: hidden`, but not things like being clipped by an `overflow: hidden` parent or being outside the viewport.
Parameters
element `HTMLElement`
Returns
`boolean`	Whether the element is visible.

`LiveAnnouncer`

Methods

async announce (message: `LiveAnnouncerMessage`): `Promise<void>`
Announces a message to screen readers.
Parameters
message `LiveAnnouncerMessage`	Message to be announced to the screen reader.
Returns
`Promise<void>`	Promise that will be resolved when the message is added to the DOM.

async announce (message: `LiveAnnouncerMessage`, politeness?: `AriaLivePoliteness`): `Promise<void>`
Announces a message to screen readers.
Parameters
message `LiveAnnouncerMessage`	Message to be announced to the screen reader.
politeness? `AriaLivePoliteness`	The politeness of the announcer element.
Returns
`Promise<void>`	Promise that will be resolved when the message is added to the DOM.

async announce (message: `LiveAnnouncerMessage`, duration?: `number`): `Promise<void>`
Announces a message to screen readers.
Parameters
message `LiveAnnouncerMessage`	Message to be announced to the screen reader.
duration? `number`	Time in milliseconds after which to clear out the announcer element. Note that this takes effect after the message has been added to the DOM, which can be up to 100ms after `announce` has been called.
Returns
`Promise<void>`	Promise that will be resolved when the message is added to the DOM.

async announce (message: `LiveAnnouncerMessage`, politeness?: `AriaLivePoliteness`, duration?: `number`): `Promise<void>`
Announces a message to screen readers.
Parameters
message `LiveAnnouncerMessage`	Message to be announced to the screen reader.
politeness? `AriaLivePoliteness`	The politeness of the announcer element.
duration? `number`	Time in milliseconds after which to clear out the announcer element. Note that this takes effect after the message has been added to the DOM, which can be up to 100ms after `announce` has been called.
Returns
`Promise<void>`	Promise that will be resolved when the message is added to the DOM.

clear ():
Clears the current text from the announcer element. Can be used to prevent screen readers from reading the text out again while the user is going through the page landmarks.

`FocusMonitor`

Monitors mouse and keyboard events to determine the cause of focus events.

Methods

focusVia (element: `HTMLElement`, origin: `FocusOrigin`, options?: `FocusOptions`): `void`
Focuses the element via the specified focus origin.
Parameters
element `HTMLElement`	Element to focus.
origin `FocusOrigin`	Focus origin.
options? `FocusOptions`	Options that can be used to configure the focus behavior.

focusVia (element: `ElementRef<HTMLElement>`, origin: `FocusOrigin`, options?: `FocusOptions`): `void`
Focuses the element via the specified focus origin.
Parameters
element `ElementRef<HTMLElement>`	Element to focus.
origin `FocusOrigin`	Focus origin.
options? `FocusOptions`	Options that can be used to configure the focus behavior.

monitor (element: `HTMLElement`, checkChildren?: `boolean`): `Observable<FocusOrigin>`
Monitors focus on an element and applies appropriate CSS classes.
Parameters
element `HTMLElement`	The element to monitor
checkChildren? `boolean`	Whether to count the element as focused when its children are focused.
Returns
`Observable<FocusOrigin>`	An observable that emits when the focus state of the element changes. When the element is blurred, null will be emitted.

monitor (element: `ElementRef<HTMLElement>`, checkChildren?: `boolean`): `Observable<FocusOrigin>`
Monitors focus on an element and applies appropriate CSS classes.
Parameters
element `ElementRef<HTMLElement>`	The element to monitor
checkChildren? `boolean`	Whether to count the element as focused when its children are focused.
Returns
`Observable<FocusOrigin>`	An observable that emits when the focus state of the element changes. When the element is blurred, null will be emitted.

stopMonitoring (element: `HTMLElement \| ElementRef<HTMLElement>`): `void`
Parameters
element `HTMLElement \| ElementRef<HTMLElement>`

`CdkTrapFocus`

Directive for trapping focus within a region.

Selector: [cdkTrapFocus]

Exported as: cdkTrapFocus

Properties

Name	Description
@Input({ alias: 'cdkTrapFocusAutoCapture', transform: booleanAttribute }) `autoCapture: boolean`	Whether the directive should automatically move focus into the trapped region upon initialization and return focus to the previous activeElement upon destruction.
@Input({ alias: 'cdkTrapFocus', transform: booleanAttribute }) `enabled: boolean`	Whether the focus trap is active.
`focusTrap: FocusTrap`	Underlying FocusTrap instance.

`CdkAriaLive`

A directive that works similarly to aria-live, but uses the LiveAnnouncer to ensure compatibility with a wider range of browsers and screen readers.

Selector: [cdkAriaLive]

Exported as: cdkAriaLive

Properties

Name	Description
@Input('cdkAriaLiveDuration') `duration: number`	Time in milliseconds after which to clear out the announcer element.
@Input('cdkAriaLive') `politeness: AriaLivePoliteness`	The aria-live politeness level to use when announcing messages.

`CdkMonitorFocus`

Directive that determines how a particular element was focused (via keyboard, mouse, touch, or programmatically) and adds corresponding classes to the element.

There are two variants of this directive:

1) cdkMonitorElementFocus: does not consider an element to be focused if one of its children is focused. 2) cdkMonitorSubtreeFocus: considers an element focused if it or any of its children are focused.

Selector: [cdkMonitorElementFocus] [cdkMonitorSubtreeFocus]

Exported as: cdkMonitorFocus

Properties

Name	Description
@Output() `cdkFocusChange: EventEmitter<FocusOrigin>`
`focusOrigin: FocusOrigin`

`ActiveDescendantKeyManager` extends ListKeyManager

Properties

Name	Description
`activeItem: T \| null`	The active item.
`activeItemIndex: number \| null`	Index of the currently active item.
`change: Subject<number>`	Stream that emits whenever the active item of the list manager changes.
`tabOut: Subject<void>`	Stream that emits any time the TAB key is pressed, so components can react when focus is shifted off of the list.

Methods

cancelTypeahead (): `this`
Cancels the current typeahead sequence.
Returns
`this`

destroy ():
Cleans up the key manager.

isTyping (): `boolean`
Gets whether the user is currently typing into the manager using the typeahead feature.
Returns
`boolean`

onKeydown (event: `KeyboardEvent`): `void`
Sets the active item depending on the key event passed in.
event `KeyboardEvent`	Keyboard event to be used for determining which element should be active.

onKeydown (event: KeyboardEvent): void

Sets the active item depending on the key event passed in.

Parameters

event

KeyboardEvent

Keyboard event to be used for determining which element should be active.

setActiveItem (index: `number`): `void`
Sets the active item to the item at the specified index and adds the active styles to the newly active item. Also removes active styles from the previously active item.
index `number`	Index of the item to be set as active.

setActiveItem (index: number): void

Sets the active item to the item at the specified index and adds the active styles to the newly active item. Also removes active styles from the previously active item.

Parameters

index

number

Index of the item to be set as active.

setActiveItem (item: `T`): `void`
Sets the active item to the item to the specified one and adds the active styles to the it. Also removes active styles from the previously active item.
item `T`	Item to be set as active.

setActiveItem (item: T): void

Sets the active item to the item to the specified one and adds the active styles to the it. Also removes active styles from the previously active item.

Parameters

item

T

Item to be set as active.

setActiveItem (item: `number \| T`): `void`
Sets the active item to the item to the specified one and adds the active styles to the it. Also removes active styles from the previously active item.
item `number \| T`	Item to be set as active.

setActiveItem (item: number | T): void

Sets the active item to the item to the specified one and adds the active styles to the it. Also removes active styles from the previously active item.

Parameters

item

number | T

Item to be set as active.

setFirstItemActive (): `void`
Sets the active item to the first enabled item in the list.

setLastItemActive (): `void`
Sets the active item to the last enabled item in the list.

setNextItemActive (): `void`
Sets the active item to the next enabled item in the list.

setPreviousItemActive (): `void`
Sets the active item to a previous enabled item in the list.

skipPredicate (predicate: `(item: T) => boolean`): `this`
Sets the predicate function that determines which items should be skipped by the list key manager.
Parameters
predicate `(item: T) => boolean`	Function that determines whether the given item should be skipped.
Returns
`this`

updateActiveItem (index: `number`): `void`
Allows setting the active without any other effects.
index `number`	Index of the item to be set as active.

updateActiveItem (index: number): void

Allows setting the active without any other effects.

Parameters

index

number

Index of the item to be set as active.

updateActiveItem (item: `T`): `void`
Allows setting the active item without any other effects.
item `T`	Item to be set as active.

updateActiveItem (item: T): void

Allows setting the active item without any other effects.

Parameters

item

T

Item to be set as active.

withAllowedModifierKeys (keys: `ListKeyManagerModifierKey[]`): `this`
Modifier keys which are allowed to be held down and whose default actions will be prevented as the user is pressing the arrow keys. Defaults to not allowing any modifier keys.
Parameters
keys `ListKeyManagerModifierKey[]`
Returns
`this`

withHomeAndEnd (enabled: `boolean = true`): `this`
Configures the key manager to activate the first and last items respectively when the Home or End key is pressed.
Parameters
enabled `boolean = true`	Whether pressing the Home or End key activates the first/last item.
Returns
`this`

withHorizontalOrientation (direction: `"ltr" \| "rtl" \| null`): `this`
Configures the key manager to move the selection horizontally. Passing in `null` will disable horizontal movement.
Parameters
direction `"ltr" \| "rtl" \| null`	Direction in which the selection can be moved.
Returns
`this`

withPageUpDown (enabled: `boolean = true`, delta: `number = 10`): `this`
Configures the key manager to activate every 10th, configured or first/last element in up/down direction respectively when the Page-Up or Page-Down key is pressed.
Parameters
enabled `boolean = true`	Whether pressing the Page-Up or Page-Down key activates the first/last item.
delta `number = 10`	Whether pressing the Home or End key activates the first/last item.
Returns
`this`

withTypeAhead (debounceInterval: `number = 200`): `this`
Turns on typeahead mode which allows users to set the active item by typing.
Parameters
debounceInterval `number = 200`	Time to wait after the last keystroke before setting the active item.
Returns
`this`

withVerticalOrientation (enabled: `boolean = true`): `this`
Configures whether the key manager should be able to move the selection vertically.
Parameters
enabled `boolean = true`	Whether vertical selection should be enabled.
Returns
`this`

withWrap (shouldWrap: `boolean = true`): `this`
Configures wrapping mode, which determines whether the active item will wrap to the other end of list when there are no more items in the given direction.
Parameters
shouldWrap `boolean = true`	Whether the list should wrap when reaching the end.
Returns
`this`

`FocusKeyManager` extends ListKeyManager

Properties

Name	Description
`activeItem: T \| null`	The active item.
`activeItemIndex: number \| null`	Index of the currently active item.
`change: Subject<number>`	Stream that emits whenever the active item of the list manager changes.
`tabOut: Subject<void>`	Stream that emits any time the TAB key is pressed, so components can react when focus is shifted off of the list.

Methods

cancelTypeahead (): `this`
Cancels the current typeahead sequence.
Returns
`this`

destroy ():
Cleans up the key manager.

isTyping (): `boolean`
Gets whether the user is currently typing into the manager using the typeahead feature.
Returns
`boolean`

onKeydown (event: KeyboardEvent): void

Sets the active item depending on the key event passed in.

Parameters

event

KeyboardEvent

Keyboard event to be used for determining which element should be active.

setActiveItem (index: number): void

Sets the active item to the item at the specified index and focuses the newly active item.

Parameters

index

number

Index of the item to be set as active.

setActiveItem (item: T): void

Sets the active item to the item that is specified and focuses it.

Parameters

item

T

Item to be set as active.

setActiveItem (item: number | T): void

Sets the active item to the item that is specified and focuses it.

Parameters

item

number | T

Item to be set as active.

setFirstItemActive (): `void`
Sets the active item to the first enabled item in the list.

setFocusOrigin (origin: `FocusOrigin`): `this`
Sets the focus origin that will be passed in to the items for any subsequent `focus` calls.
Parameters
origin `FocusOrigin`	Focus origin to be used when focusing items.
Returns
`this`

setLastItemActive (): `void`
Sets the active item to the last enabled item in the list.

setNextItemActive (): `void`
Sets the active item to the next enabled item in the list.

setPreviousItemActive (): `void`
Sets the active item to a previous enabled item in the list.

skipPredicate (predicate: `(item: T) => boolean`): `this`
Sets the predicate function that determines which items should be skipped by the list key manager.
Parameters
predicate `(item: T) => boolean`	Function that determines whether the given item should be skipped.
Returns
`this`

updateActiveItem (index: number): void

Allows setting the active without any other effects.

Parameters

index

number

Index of the item to be set as active.

updateActiveItem (item: T): void

Allows setting the active item without any other effects.

Parameters

item

T

Item to be set as active.

withAllowedModifierKeys (keys: `ListKeyManagerModifierKey[]`): `this`
Modifier keys which are allowed to be held down and whose default actions will be prevented as the user is pressing the arrow keys. Defaults to not allowing any modifier keys.
Parameters
keys `ListKeyManagerModifierKey[]`
Returns
`this`

withHomeAndEnd (enabled: `boolean = true`): `this`
Configures the key manager to activate the first and last items respectively when the Home or End key is pressed.
Parameters
enabled `boolean = true`	Whether pressing the Home or End key activates the first/last item.
Returns
`this`

withHorizontalOrientation (direction: `"ltr" \| "rtl" \| null`): `this`
Configures the key manager to move the selection horizontally. Passing in `null` will disable horizontal movement.
Parameters
direction `"ltr" \| "rtl" \| null`	Direction in which the selection can be moved.
Returns
`this`

withPageUpDown (enabled: `boolean = true`, delta: `number = 10`): `this`
Configures the key manager to activate every 10th, configured or first/last element in up/down direction respectively when the Page-Up or Page-Down key is pressed.
Parameters
enabled `boolean = true`	Whether pressing the Page-Up or Page-Down key activates the first/last item.
delta `number = 10`	Whether pressing the Home or End key activates the first/last item.
Returns
`this`

withTypeAhead (debounceInterval: `number = 200`): `this`
Turns on typeahead mode which allows users to set the active item by typing.
Parameters
debounceInterval `number = 200`	Time to wait after the last keystroke before setting the active item.
Returns
`this`

withVerticalOrientation (enabled: `boolean = true`): `this`
Configures whether the key manager should be able to move the selection vertically.
Parameters
enabled `boolean = true`	Whether vertical selection should be enabled.
Returns
`this`

withWrap (shouldWrap: `boolean = true`): `this`
Configures wrapping mode, which determines whether the active item will wrap to the other end of list when there are no more items in the given direction.
Parameters
shouldWrap `boolean = true`	Whether the list should wrap when reaching the end.
Returns
`this`

`ListKeyManager`

This class manages keyboard events for selectable lists. If you pass it a query list of items, it will set the active item correctly when arrow events occur.

Properties

Name	Description
`activeItem: T \| null`	The active item.
`activeItemIndex: number \| null`	Index of the currently active item.
`change: Subject<number>`	Stream that emits whenever the active item of the list manager changes.
`tabOut: Subject<void>`	Stream that emits any time the TAB key is pressed, so components can react when focus is shifted off of the list.

Methods

cancelTypeahead (): `this`
Cancels the current typeahead sequence.
Returns
`this`

destroy ():
Cleans up the key manager.

isTyping (): `boolean`
Gets whether the user is currently typing into the manager using the typeahead feature.
Returns
`boolean`

onKeydown (event: KeyboardEvent): void

Sets the active item depending on the key event passed in.

Parameters

event

KeyboardEvent

Keyboard event to be used for determining which element should be active.

setActiveItem (index: number): void

Sets the active item to the item at the index specified.

Parameters

index

number

The index of the item to be set as active.

setActiveItem (item: T): void

Sets the active item to the specified item.

Parameters

item

T

The item to be set as active.

setActiveItem (item: number | T): void

Sets the active item to the specified item.

Parameters

item

number | T

The item to be set as active.

setFirstItemActive (): `void`
Sets the active item to the first enabled item in the list.

setLastItemActive (): `void`
Sets the active item to the last enabled item in the list.

setNextItemActive (): `void`
Sets the active item to the next enabled item in the list.

setPreviousItemActive (): `void`
Sets the active item to a previous enabled item in the list.

skipPredicate (predicate: `(item: T) => boolean`): `this`
Sets the predicate function that determines which items should be skipped by the list key manager.
Parameters
predicate `(item: T) => boolean`	Function that determines whether the given item should be skipped.
Returns
`this`

updateActiveItem (index: number): void

Allows setting the active without any other effects.

Parameters

index

number

Index of the item to be set as active.

updateActiveItem (item: T): void

Allows setting the active item without any other effects.

Parameters

item

T

Item to be set as active.

withAllowedModifierKeys (keys: `ListKeyManagerModifierKey[]`): `this`
Modifier keys which are allowed to be held down and whose default actions will be prevented as the user is pressing the arrow keys. Defaults to not allowing any modifier keys.
Parameters
keys `ListKeyManagerModifierKey[]`
Returns
`this`

withHomeAndEnd (enabled: `boolean = true`): `this`
Configures the key manager to activate the first and last items respectively when the Home or End key is pressed.
Parameters
enabled `boolean = true`	Whether pressing the Home or End key activates the first/last item.
Returns
`this`

withHorizontalOrientation (direction: `"ltr" \| "rtl" \| null`): `this`
Configures the key manager to move the selection horizontally. Passing in `null` will disable horizontal movement.
Parameters
direction `"ltr" \| "rtl" \| null`	Direction in which the selection can be moved.
Returns
`this`

withPageUpDown (enabled: `boolean = true`, delta: `number = 10`): `this`
Configures the key manager to activate every 10th, configured or first/last element in up/down direction respectively when the Page-Up or Page-Down key is pressed.
Parameters
enabled `boolean = true`	Whether pressing the Page-Up or Page-Down key activates the first/last item.
delta `number = 10`	Whether pressing the Home or End key activates the first/last item.
Returns
`this`

withTypeAhead (debounceInterval: `number = 200`): `this`
Turns on typeahead mode which allows users to set the active item by typing.
Parameters
debounceInterval `number = 200`	Time to wait after the last keystroke before setting the active item.
Returns
`this`

withVerticalOrientation (enabled: `boolean = true`): `this`
Configures whether the key manager should be able to move the selection vertically.
Parameters
enabled `boolean = true`	Whether vertical selection should be enabled.
Returns
`this`

withWrap (shouldWrap: `boolean = true`): `this`
Configures wrapping mode, which determines whether the active item will wrap to the other end of list when there are no more items in the given direction.
Parameters
shouldWrap `boolean = true`	Whether the list should wrap when reaching the end.
Returns
`this`

`TreeKeyManager`

This class manages keyboard events for trees. If you pass it a QueryList or other list of tree items, it will set the active item, focus, handle expansion and typeahead correctly when keyboard events occur.

Properties

Name	Description
`change: Subject<T \| null>`	Stream that emits any time the focused item changes.

Methods

destroy ():
Cleans up the key manager.

focusItem (index: `number`, options?: `{ emitChangeEvent?: boolean \| undefined; }`): `void`
Focus the provided item by index.
Parameters
index `number`	The index of the item to focus.
options? `{ emitChangeEvent?: boolean \| undefined; }`	Additional focusing options.

focusItem (item: `T`, options?: `{ emitChangeEvent?: boolean \| undefined; }`): `void`
Parameters
item `T`
options? `{ emitChangeEvent?: boolean \| undefined; }`

focusItem (itemOrIndex: `number \| T`, options?: `{ emitChangeEvent?: boolean \| undefined; }`): `void`
Parameters
itemOrIndex `number \| T`
options? `{ emitChangeEvent?: boolean \| undefined; }`

getActiveItem (): `T \| null`
The currently active item.
Returns
`T \| null`

getActiveItemIndex (): `number \| null`
Index of the currently active item.
Returns
`number \| null`

onKeydown (event: KeyboardEvent):

Handles a keyboard event on the tree.

Parameters

event

KeyboardEvent

Keyboard event that represents the user interaction with the tree.

`ConfigurableFocusTrap` extends FocusTrap

Class that allows for trapping focus within a DOM element.

This class uses a strategy pattern that determines how it traps focus. See FocusTrapInertStrategy.

Properties

Name	Description
`enabled: boolean`	Whether the FocusTrap is enabled.

Methods

attachAnchors (): boolean

Inserts the anchors into the DOM. This is usually done automatically in the constructor, but can be deferred for cases like directives with *ngIf.

Returns

boolean

Whether the focus trap managed to attach successfully. This may not be the case if the target element isn't currently in the DOM.

destroy ():
Notifies the FocusTrapManager that this FocusTrap will be destroyed.

focusFirstTabbableElement (options?: `FocusOptions`): `boolean`
Focuses the first tabbable element within the focus trap region.
Parameters
options? `FocusOptions`
Returns
`boolean`	Whether focus was moved successfully.

async focusFirstTabbableElementWhenReady (options?: `FocusOptions`): `Promise<boolean>`
Waits for the zone to stabilize, then focuses the first tabbable element within the focus trap region.
Parameters
options? `FocusOptions`
Returns
`Promise<boolean>`	Returns a promise that resolves with a boolean, depending on whether focus was moved successfully.

focusInitialElement (options?: `FocusOptions`): `boolean`
Focuses the element that should be focused when the focus trap is initialized.
Parameters
options? `FocusOptions`
Returns
`boolean`	Whether focus was moved successfully.

async focusInitialElementWhenReady (options?: `FocusOptions`): `Promise<boolean>`
Waits for the zone to stabilize, then focuses the first tabbable element.
Parameters
options? `FocusOptions`
Returns
`Promise<boolean>`	Returns a promise that resolves with a boolean, depending on whether focus was moved successfully.

focusLastTabbableElement (options?: `FocusOptions`): `boolean`
Focuses the last tabbable element within the focus trap region.
Parameters
options? `FocusOptions`
Returns
`boolean`	Whether focus was moved successfully.

async focusLastTabbableElementWhenReady (options?: `FocusOptions`): `Promise<boolean>`
Waits for the zone to stabilize, then focuses the last tabbable element within the focus trap region.
Parameters
options? `FocusOptions`
Returns
`Promise<boolean>`	Returns a promise that resolves with a boolean, depending on whether focus was moved successfully.

hasAttached (): `boolean`
Checks whether the focus trap has successfully been attached.
Returns
`boolean`

`EventListenerFocusTrapInertStrategy`

Lightweight FocusTrapInertStrategy that adds a document focus event listener to redirect focus back inside the FocusTrap.

Methods

allowFocus (focusTrap: `ConfigurableFocusTrap`): `void`
Removes the event listener added in preventFocus.
Parameters
focusTrap `ConfigurableFocusTrap`

preventFocus (focusTrap: `ConfigurableFocusTrap`): `void`
Adds a document event listener that keeps focus inside the FocusTrap.
Parameters
focusTrap `ConfigurableFocusTrap`

`FocusTrap`

Class that allows for trapping focus within a DOM element.

This class currently uses a relatively simple approach to focus trapping. It assumes that the tab order is the same as DOM order, which is not necessarily true. Things like tabIndex > 0, flex order, and shadow roots can cause the two to be misaligned.

Properties

Name	Description
`enabled: boolean`	Whether the focus trap is active.
`endAnchorListener: () => { const isSuccess = this.focusFirstTabbableElement(); if (!isSuccess && this._checker.isFocusable(this._element)) { this._element.focus(); } }`
`startAnchorListener: () => { const isSuccess = this.focusLastTabbableElement(); if (!isSuccess && this._checker.isFocusable(this._element)) { this._element.focus(); } }`

Methods

attachAnchors (): boolean

Inserts the anchors into the DOM. This is usually done automatically in the constructor, but can be deferred for cases like directives with *ngIf.

Returns

boolean

Whether the focus trap managed to attach successfully. This may not be the case if the target element isn't currently in the DOM.

destroy ():
Destroys the focus trap by cleaning up the anchors.

focusFirstTabbableElement (options?: `FocusOptions`): `boolean`
Focuses the first tabbable element within the focus trap region.
Parameters
options? `FocusOptions`
Returns
`boolean`	Whether focus was moved successfully.

async focusFirstTabbableElementWhenReady (options?: `FocusOptions`): `Promise<boolean>`
Waits for the zone to stabilize, then focuses the first tabbable element within the focus trap region.
Parameters
options? `FocusOptions`
Returns
`Promise<boolean>`	Returns a promise that resolves with a boolean, depending on whether focus was moved successfully.

focusInitialElement (options?: `FocusOptions`): `boolean`
Focuses the element that should be focused when the focus trap is initialized.
Parameters
options? `FocusOptions`
Returns
`boolean`	Whether focus was moved successfully.

async focusInitialElementWhenReady (options?: `FocusOptions`): `Promise<boolean>`
Waits for the zone to stabilize, then focuses the first tabbable element.
Parameters
options? `FocusOptions`
Returns
`Promise<boolean>`	Returns a promise that resolves with a boolean, depending on whether focus was moved successfully.

focusLastTabbableElement (options?: `FocusOptions`): `boolean`
Focuses the last tabbable element within the focus trap region.
Parameters
options? `FocusOptions`
Returns
`boolean`	Whether focus was moved successfully.

async focusLastTabbableElementWhenReady (options?: `FocusOptions`): `Promise<boolean>`
Waits for the zone to stabilize, then focuses the last tabbable element within the focus trap region.
Parameters
options? `FocusOptions`
Returns
`Promise<boolean>`	Returns a promise that resolves with a boolean, depending on whether focus was moved successfully.

hasAttached (): `boolean`
Checks whether the focus trap has successfully been attached.
Returns
`boolean`

toggleAnchors (enabled:: , enabled: `boolean`):
Toggles the`tabindex` of both anchors to either trap Tab focus or allow it to escape.
Parameters
enabled:	Whether the anchors should trap Tab.
enabled `boolean`

`IsFocusableConfig`

Configuration for the isFocusable method.

Properties

Name	Description
`ignoreInert: boolean`	Whether to count an element as focusable even if it is inert or inside an inert subtree.
`ignoreVisibility: boolean`	Whether to count an element as focusable even if it is not currently visible.

`RegisteredMessage`

Interface used to register message elements and keep a count of how many registrations have the same message and the reference to the message element used for the aria-describedby.

Properties

Name	Description
`messageElement: Element`	The element containing the message.
`referenceCount: number`	The number of elements that reference this message element via `aria-describedby`.

`InputModalityDetectorOptions`

Options to configure the behavior of the InputModalityDetector.

Properties

Name	Description
`ignoreKeys: number[]`	Keys to ignore when detecting keyboard input modality.

`Highlightable`

This is the interface for highlightable items (used by the ActiveDescendantKeyManager). Each item must know how to style itself as active or inactive and whether or not it is currently disabled.

Methods

setActiveStyles (): `void`
Applies the styles for an active item to this item.

setInactiveStyles (): `void`
Applies the styles for an inactive item to this item.

`FocusableOption`

This is the interface for focusable items (used by the FocusKeyManager). Each item must know how to focus itself, whether or not it is currently disabled and be able to supply its label.

Methods

focus (origin?: `FocusOrigin`): `void`
Focuses the `FocusableOption`.
Parameters
origin? `FocusOrigin`

`ListKeyManagerOption`

This interface is for items that can be passed to a ListKeyManager.

Properties

Name	Description
`disabled: boolean`	Whether the option is disabled.

Methods

getLabel (): `string`
Gets the label for this option.
Returns
`string`

`TreeKeyManagerItem`

Represents an item within a tree that can be passed to a TreeKeyManager.

Properties

Name	Description
`isDisabled: (() => boolean) \| boolean`	Whether the item is disabled.
`isExpanded: (() => boolean) \| boolean`	Determines if the item is currently expanded.

Methods

activate (): `void`
Perform the main action (i.e. selection) for this item.

collapse (): `void`
Collapses the item, hiding its children.

expand (): `void`
Expands the item, showing its children.

focus (): `void`
Focuses the item. This should provide some indication to the user that this item is focused.

getChildren (): `TreeKeyManagerItem[] \| Observable<TreeKeyManagerItem[]>`
Retrieves the children for this item.
Returns
`TreeKeyManagerItem[] \| Observable<TreeKeyManagerItem[]>`

getLabel (): `string`
The user-facing label for this item.
Returns
`string`

getParent (): `TreeKeyManagerItem \| null`
Retrieves the parent for this item. This is `null` if there is no parent.
Returns
`TreeKeyManagerItem \| null`

makeFocusable (): `void`
Sets the item to be focusable without actually focusing it.

unfocus (): `void`
Unfocus the item. This should remove the focus state.

`TreeKeyManagerOptions`

Configuration for the TreeKeyManager.

Properties

Name	Description
`horizontalOrientation: 'rtl' \| 'ltr'`	The direction in which the tree items are laid out horizontally. This influences which key will be interpreted as expand or collapse.
`shouldActivationFollowFocus: boolean`	If true, then the key manager will call `activate` in addition to calling `focus` when a particular item is focused.
`skipPredicate: (item: T) => boolean`	If provided, navigation "skips" over items that pass the given predicate. If the item is to be skipped, predicate function should return false.
`trackBy: (treeItem: T) => unknown`	If provided, determines how the key manager determines if two items are equivalent. It should provide a unique key for each unique tree item. If two tree items are equivalent, then this function should return the same value.
`typeAheadDebounceInterval: true \| number`	If a value is provided, enables typeahead mode, which allows users to set the active item by typing the visible label of the item. If a number is provided, this will be the time to wait after the last keystroke before setting the active item. If `true` is provided, the default interval of 200ms will be used.

`TreeKeyManagerStrategy`

Properties

Name	Description
`change: Subject<T \| null>`	Stream that emits any time the focused item changes.

Methods

destroy (): `void`
Cleans up the key manager.

focusItem (index: `number`, options?: `{ emitChangeEvent?: boolean \| undefined; }`): `void`
Focus the provided item by index. Updates the state of the currently active item. Emits to `change` stream if active item Changes.
Parameters
index `number`	The index of the item to focus.
options? `{ emitChangeEvent?: boolean \| undefined; }`	Additional focusing options.

getActiveItem (): `T \| null`
The currently active item.
Returns
`T \| null`

getActiveItemIndex (): `number \| null`
Index of the currently active item.
Returns
`number \| null`

onKeydown (event: KeyboardEvent): void

Handles a keyboard event on the tree.

Parameters

event

KeyboardEvent

Keyboard event that represents the user interaction with the tree.

`ConfigurableFocusTrapConfig`

Options for creating a ConfigurableFocusTrap.

Properties

Name	Description
`defer: boolean`	Whether to defer the creation of FocusTrap elements to be done manually by the user.

`FocusTrapInertStrategy`

A strategy that dictates how FocusTrap should prevent elements outside of the FocusTrap from being focused.

Methods

allowFocus (focusTrap: `FocusTrap`): `void`
Reverts elements made unfocusable by preventFocus to their previous state.
Parameters
focusTrap `FocusTrap`

preventFocus (focusTrap: `FocusTrap`): `void`
Makes all elements outside focusTrap unfocusable.
Parameters
focusTrap `FocusTrap`

`LiveAnnouncerDefaultOptions`

Object that can be used to configure the default options for the LiveAnnouncer.

Properties

Name	Description
`duration: number`	Default duration for the announcement messages.
`politeness: AriaLivePoliteness`	Default politeness for the announcements.

`FocusOptions`

Corresponds to the options that can be passed to the native focus event. via https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus

Properties

Name	Description
`preventScroll: boolean`	Whether the browser should scroll to the element when it is focused.

`FocusMonitorOptions`

Injectable service-level options for FocusMonitor.

Properties

Name	Description
`detectionMode: FocusMonitorDetectionMode`

addAriaReferencedId (el: `Element`, attr: `aria-${string}`, id: `string`):
Adds the given ID to the specified ARIA attribute on an element. Used for attributes such as aria-labelledby, aria-owns, etc.
Parameters
el `Element`
attr `aria-${string}`
id `string`

removeAriaReferencedId (el: `Element`, attr: `aria-${string}`, id: `string`):
Removes the given ID from the specified ARIA attribute on an element. Used for attributes such as aria-labelledby, aria-owns, etc.
Parameters
el `Element`
attr `aria-${string}`
id `string`

getAriaReferenceIds (el: `Element`, attr: `string`): `string[]`
Gets the list of IDs referenced by the given ARIA attribute on an element. Used for attributes such as aria-labelledby, aria-owns, etc.
Parameters
el `Element`
attr `string`
Returns
`string[]`

isFakeMousedownFromScreenReader (event: `MouseEvent`): `boolean`
Gets whether an event could be a faked `mousedown` event dispatched by a screen reader.
Parameters
event `MouseEvent`
Returns
`boolean`

isFakeTouchstartFromScreenReader (event: `TouchEvent`): `boolean`
Gets whether an event could be a faked `touchstart` event dispatched by a screen reader.
Parameters
event `TouchEvent`
Returns
`boolean`

`InputModality`

The input modalities detected by this service. Null is used if the input modality is unknown.

type InputModality = 'keyboard' | 'mouse' | 'touch' | null;

`ListKeyManagerModifierKey`

Modifier keys handled by the ListKeyManager.

type ListKeyManagerModifierKey = 'altKey' | 'ctrlKey' | 'metaKey' | 'shiftKey';

`TreeKeyManagerFactory`

type TreeKeyManagerFactory = (items: Observable | QueryList | T[], options: TreeKeyManagerOptions) => TreeKeyManagerStrategy;

`LiveAnnouncerMessage`

Possible types for a message that can be announced by the LiveAnnouncer.

type LiveAnnouncerMessage = string | SafeHtml;

`AriaLivePoliteness`

Possible politeness levels.

type AriaLivePoliteness = 'off' | 'polite' | 'assertive';

`FocusOrigin`

type FocusOrigin = 'touch' | 'mouse' | 'keyboard' | 'program' | null;

`INPUT_MODALITY_DETECTOR_DEFAULT_OPTIONS`

Default options for the InputModalityDetector.

Modifier keys are ignored by default (i.e. when pressed won't cause the service to detect keyboard input modality) for two reasons:

Modifier keys are commonly used with mouse to perform actions such as 'right click' or 'open in new tab', and are thus less representative of actual keyboard interaction.
VoiceOver triggers some keyboard events when linearly navigating with Control + Option (but confusingly not with Caps Lock). Thus, to have parity with other screen readers, we ignore these keys so as to not update the input modality.

Note that we do not by default ignore the right Meta key on Safari because it has the same key code as the ContextMenu key on other browsers. When we switch to using event.key, we can distinguish between the two.

const INPUT_MODALITY_DETECTOR_DEFAULT_OPTIONS: InputModalityDetectorOptions;

`INPUT_MODALITY_DETECTOR_OPTIONS`

Injectable options for the InputModalityDetector. These are shallowly merged with the default options.

const INPUT_MODALITY_DETECTOR_OPTIONS: InjectionToken;

`TREE_KEY_MANAGER`

Injection token that determines the key manager to use.

const TREE_KEY_MANAGER: InjectionToken>;

`FOCUS_TRAP_INERT_STRATEGY`

The injection token used to specify the inert strategy.

const FOCUS_TRAP_INERT_STRATEGY: InjectionToken;

`LIVE_ANNOUNCER_ELEMENT_TOKEN`

const LIVE_ANNOUNCER_ELEMENT_TOKEN: InjectionToken;

`LIVE_ANNOUNCER_DEFAULT_OPTIONS`

Injection token that can be used to configure the default options for the LiveAnnouncer.

const LIVE_ANNOUNCER_DEFAULT_OPTIONS: InjectionToken;

`FOCUS_MONITOR_DEFAULT_OPTIONS`

InjectionToken for FocusMonitorOptions.

const FOCUS_MONITOR_DEFAULT_OPTIONS: InjectionToken;

API reference for Angular CDK a11y

Services link

AriaDescriber link

Methods

InputModalityDetector link

Properties

HighContrastModeDetector link

Methods

ConfigurableFocusTrapFactory link

Methods

FocusTrapFactory link

Methods

InteractivityChecker link

Methods

LiveAnnouncer link

Methods

FocusMonitor link

Methods

Directives link

CdkTrapFocus link

Properties

CdkAriaLive link

Properties

CdkMonitorFocus link

Properties

Classes link

ActiveDescendantKeyManager extends ListKeyManager link

Properties

Methods

FocusKeyManager extends ListKeyManager link

Properties

Methods

ListKeyManager link

Properties

Methods

TreeKeyManager link

Properties

Methods

ConfigurableFocusTrap extends FocusTrap link

Properties

Methods

EventListenerFocusTrapInertStrategy link

Methods

FocusTrap link

Properties

Methods

IsFocusableConfig link

Properties

Interfaces link

RegisteredMessage link

Properties

InputModalityDetectorOptions link

Properties

Highlightable link

Methods

FocusableOption link

Methods

ListKeyManagerOption link

Properties

Methods

TreeKeyManagerItem link

Properties

Methods

TreeKeyManagerOptions link

Properties

TreeKeyManagerStrategy link

Properties

Methods

ConfigurableFocusTrapConfig link

Properties

FocusTrapInertStrategy link

Methods

LiveAnnouncerDefaultOptions link

Properties

FocusOptions link

Properties

FocusMonitorOptions link

Properties

Functions link

Type aliases link

Services

`AriaDescriber`

`InputModalityDetector`

`HighContrastModeDetector`

`ConfigurableFocusTrapFactory`

`FocusTrapFactory`

`InteractivityChecker`

`LiveAnnouncer`

`FocusMonitor`

Directives

`CdkTrapFocus`

`CdkAriaLive`

`CdkMonitorFocus`

Classes

`ActiveDescendantKeyManager` extends ListKeyManager

`FocusKeyManager` extends ListKeyManager

`ListKeyManager`

`TreeKeyManager`

`ConfigurableFocusTrap` extends FocusTrap

`EventListenerFocusTrapInertStrategy`

`FocusTrap`

`IsFocusableConfig`

Interfaces

`RegisteredMessage`

`InputModalityDetectorOptions`

`Highlightable`

`FocusableOption`

`ListKeyManagerOption`

`TreeKeyManagerItem`

`TreeKeyManagerOptions`

`TreeKeyManagerStrategy`

`ConfigurableFocusTrapConfig`

`FocusTrapInertStrategy`

`LiveAnnouncerDefaultOptions`

`FocusOptions`

`FocusMonitorOptions`

Functions

Type aliases

`InputModality`

`ListKeyManagerModifierKey`

`TreeKeyManagerFactory`

`LiveAnnouncerMessage`

`AriaLivePoliteness`

`FocusOrigin`

Constants

`INPUT_MODALITY_DETECTOR_DEFAULT_OPTIONS`

`INPUT_MODALITY_DETECTOR_OPTIONS`

`TREE_KEY_MANAGER`

`FOCUS_TRAP_INERT_STRATEGY`

`LIVE_ANNOUNCER_ELEMENT_TOKEN`

`LIVE_ANNOUNCER_DEFAULT_OPTIONS`

`FOCUS_MONITOR_DEFAULT_OPTIONS`