Accessibility

API for a11y

API reference for Angular CDK a11y

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

Factory that allows easy instantiation of focus traps.

Methods
create

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.

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

Methods
isDisabled

Gets whether an element is disabled.

Parameters

element

HTMLElement

Element to be checked.

Returns
boolean

Whether the element is disabled.

isFocusable

Gets whether an element can be focused by the user.

Parameters

element

HTMLElement

Element to be checked.

Returns
boolean

Whether the element is focusable.

isTabbable

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

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.

Methods
announce

Announces a message to screenreaders.

Parameters

message

string

Message to be announced to the screenreader

politeness

AriaLivePoliteness = 'polite'

The politeness of the announcer element

Returns
Promise<void>

Promise that will be resolved when the message is added to the DOM.

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

Methods
focusVia

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

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

Monitors focus on an element and applies appropriate CSS classes.

Parameters

element

HTMLElement

The element to monitor

checkChildren

boolean = false

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

Stops monitoring an element and removes all focus classes.

Parameters

element

HTMLElement

The element to stop monitoring.

Directive for trapping focus within a region.

Selector: [cdkTrapFocus]

Exported as: cdkTrapFocus
Properties
NameDescription
@Input('cdkTrapFocusAutoCapture')

autoCapture: boolean

Whether the directive should automatially move focus into the trapped region upon initialization and return focus to the previous activeElement upon destruction.

@Input('cdkTrapFocus')

enabled: boolean

Whether the focus trap is active.

focusTrap: FocusTrap

Underlying FocusTrap instance.

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
NameDescription
@Input('cdkAriaLive')

politeness: AriaLivePoliteness

The aria-live politeness level to use when announcing messages.

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]

Properties
NameDescription
@Output()

cdkFocusChange: EventEmitter<FocusOrigin>

Properties
NameDescription

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
onKeydown

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

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

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.

setFirstItemActive

Sets the active item to the first enabled item in the list.

setLastItemActive

Sets the active item to the last enabled item in the list.

setNextItemActive

Sets the active item to the next enabled item in the list.

setPreviousItemActive

Sets the active item to a previous enabled item in the list.

skipPredicate

Sets the predicate function that determines which items should be skipped by the list key manager.

Parameters

predicate

(item

Function that determines whether the given item should be skipped.

Returns
this

updateActiveItem

Allows setting the active without any other effects.

Parameters

index

number

Index of the item to be set as active.

updateActiveItem

Allows setting the active item without any other effects.

Parameters

item

T

Item to be set as active.

withHorizontalOrientation

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

withTypeAhead

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

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

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

true = true

Whether the list should wrap when reaching the end.

Returns
this

Deprecated
updateActiveItemIndex

Allows setting of the activeItemIndex without any other effects.

Parameters

index

number

The new activeItemIndex.

Properties
NameDescription

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
onKeydown

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

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

Parameters

item

T

Item to be set as active.

setActiveItem

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.

setFirstItemActive

Sets the active item to the first enabled item in the list.

setFocusOrigin

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

Sets the active item to the last enabled item in the list.

setNextItemActive

Sets the active item to the next enabled item in the list.

setPreviousItemActive

Sets the active item to a previous enabled item in the list.

skipPredicate

Sets the predicate function that determines which items should be skipped by the list key manager.

Parameters

predicate

(item

Function that determines whether the given item should be skipped.

Returns
this

updateActiveItem

Allows setting the active without any other effects.

Parameters

index

number

Index of the item to be set as active.

updateActiveItem

Allows setting the active item without any other effects.

Parameters

item

T

Item to be set as active.

withHorizontalOrientation

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

withTypeAhead

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

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

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

true = true

Whether the list should wrap when reaching the end.

Returns
this

Deprecated
updateActiveItemIndex

Allows setting of the activeItemIndex without any other effects.

Parameters

index

number

The new activeItemIndex.

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
NameDescription

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
onKeydown

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

Sets the active item to the specified item.

Parameters

item

T

The item to be set as active.

setActiveItem

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

Parameters

index

number

The index of the item to be set as active.

setFirstItemActive

Sets the active item to the first enabled item in the list.

setLastItemActive

Sets the active item to the last enabled item in the list.

setNextItemActive

Sets the active item to the next enabled item in the list.

setPreviousItemActive

Sets the active item to a previous enabled item in the list.

skipPredicate

Sets the predicate function that determines which items should be skipped by the list key manager.

Parameters

predicate

(item

Function that determines whether the given item should be skipped.

Returns
this

updateActiveItem

Allows setting the active without any other effects.

Parameters

index

number

Index of the item to be set as active.

updateActiveItem

Allows setting the active item without any other effects.

Parameters

item

T

Item to be set as active.

withHorizontalOrientation

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

withTypeAhead

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

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

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

true = true

Whether the list should wrap when reaching the end.

Returns
this

Deprecated
updateActiveItemIndex

Allows setting of the activeItemIndex without any other effects.

Parameters

index

number

The new activeItemIndex.

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 to two to misalign.

Properties
NameDescription

enabled: boolean

Whether the focus trap is active.

Methods
attachAnchors

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 successfuly. 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

Focuses the first tabbable element within the focus trap region.

Returns
boolean

Whether focus was moved successfuly.

focusFirstTabbableElementWhenReady

Waits for the zone to stabilize, then focuses the first tabbable element within the focus trap region.

Returns
Promise<boolean>

Returns a promise that resolves with a boolean, depending on whether focus was moved successfuly.

focusInitialElement

Focuses the element that should be focused when the focus trap is initialized.

Returns
boolean

Whether focus was moved successfuly.

focusInitialElementWhenReady

Waits for the zone to stabilize, then either focuses the first element that the user specified, or the first tabbable element.

Returns
Promise<boolean>

Returns a promise that resolves with a boolean, depending on whether focus was moved successfuly.

focusLastTabbableElement

Focuses the last tabbable element within the focus trap region.

Returns
boolean

Whether focus was moved successfuly.

focusLastTabbableElementWhenReady

Waits for the zone to stabilize, then focuses the last tabbable element within the focus trap region.

Returns
Promise<boolean>

Returns a promise that resolves with a boolean, depending on whether focus was moved successfuly.

hasAttached

Checks whether the focus trap has successfuly been attached.

Returns
boolean

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
NameDescription

messageElement: Element

The element containing the message.

referenceCount: number

The number of elements that reference this message element via aria-describedby.

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

Applies the styles for an active item to this item.

setInactiveStyles

Applies the styles for an inactive item to this item.

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 it's label.

Methods
focus

Focuses the FocusableOption.

Parameters

origin?

FocusOrigin

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

Properties
NameDescription

disabled: boolean

Whether the option is disabled.

Methods
getLabel

Gets the label for this option.

Returns
string

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
NameDescription

preventScroll: boolean

Whether the browser should scroll to the element when it is focused.

Possible politeness levels.

Type: 'off' | 'polite' | 'assertive'

Type: 'touch' | 'mouse' | 'keyboard' | 'program' | null