import {A11yModule} from '@angular/cdk/a11y';
FocusTrapFactoryFactory that allows easy instantiation of focus traps.
| 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. |
InteractivityCheckerUtility for checking the interactivity of an element, such as whether is is focusable or tabbable.
| 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 | |
| Parameters | |
element HTMLElement | |
| Returns | |
boolean | Whether the element is visible. |
LiveAnnouncer| 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. |
FocusMonitorMonitors mouse and keyboard events to determine the cause of focus events.
| 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. |
CdkTrapFocusDirective for trapping focus within a region.
Selector: [cdkTrapFocus]
Exported as: cdkTrapFocus| Name | Description |
|---|---|
@Input('cdkTrapFocusAutoCapture')
| Whether the directive should automatially move focus into the trapped region upon initialization and return focus to the previous activeElement upon destruction. |
@Input('cdkTrapFocus')
| Whether the focus trap is active. |
| Underlying FocusTrap instance. |
CdkAriaLiveA 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| Name | Description |
|---|---|
@Input('cdkAriaLive')
| The aria-live politeness level to use when announcing messages. |
CdkMonitorFocusDirective 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]
| Name | Description |
|---|---|
@Output()
|
ActiveDescendantKeyManager extends ListKeyManager| Name | Description |
|---|---|
| The active item. |
| Index of the currently active item. |
| Stream that emits whenever the active item of the list manager changes. |
| Stream that emits any time the TAB key is pressed, so components can react when focus is shifted off of the list. |
| 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 | |
| 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. |
FocusKeyManager extends ListKeyManager| Name | Description |
|---|---|
| The active item. |
| Index of the currently active item. |
| Stream that emits whenever the active item of the list manager changes. |
| Stream that emits any time the TAB key is pressed, so components can react when focus is shifted off of the list. |
| 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 | |
| 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 | |
| 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. |
ListKeyManagerThis 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.
| Name | Description |
|---|---|
| The active item. |
| Index of the currently active item. |
| Stream that emits whenever the active item of the list manager changes. |
| Stream that emits any time the TAB key is pressed, so components can react when focus is shifted off of the list. |
| 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 | |
| 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. |
FocusTrapClass 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.
| Name | Description |
|---|---|
| Whether the focus trap is active. |
| attachAnchors | |
|---|---|
Inserts the anchors into the DOM. This is usually done automatically in the constructor, but can be deferred for cases like directives with | |
| 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 | |
RegisteredMessageInterface 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.
| Name | Description |
|---|---|
| The element containing the message. |
| The number of elements that reference this message element via |
HighlightableThis 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.
| setActiveStyles | |
|---|---|
Applies the styles for an active item to this item. |
| setInactiveStyles | |
|---|---|
Applies the styles for an inactive item to this item. |
FocusableOptionThis 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.
| focus | |
|---|---|
Focuses the | |
| Parameters | |
origin? FocusOrigin | |
ListKeyManagerOptionThis interface is for items that can be passed to a ListKeyManager.
| Name | Description |
|---|---|
| Whether the option is disabled. |
| getLabel | |
|---|---|
Gets the label for this option. | |
| Returns | |
string | |
FocusOptionsCorresponds to the options that can be passed to the native focus event. via https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus
| Name | Description |
|---|---|
| Whether the browser should scroll to the element when it is focused. |
AriaLivePolitenessPossible politeness levels.
Type: 'off' | 'polite' | 'assertive'
FocusOriginType: 'touch' | 'mouse' | 'keyboard' | 'program' | null