You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The a11y package provides a number of tools to improve accessibility, described below.
ListKeyManager
ListKeyManager manages the active option in a list of items based on keyboard interaction.
Intended to be used with components that correspond to a role="menu" or role="listbox" pattern.
Basic usage
Any component that uses a ListKeyManager will generally do three things:
Create a @ViewChildren query for the options being managed.
Initialize the ListKeyManager, passing in the options.
Forward keyboard events from the managed component to the ListKeyManager.
Each option should implement the ListKeyManagerOption interface:
Each item must also have an ID bound to the listbox's or menu's aria-activedescendant.
FocusTrap
The cdkTrapFocus directive traps Tab key focus within an element. This is intended to
be used to create accessible experience for components like modal dialogs, where focus must be
constrained.
This directive is declared in A11yModule.
Example
<divclass="my-inner-dialog-content" cdkTrapFocus><!-- Tab and Shift + Tab will not leave this element. --></div>
This directive will not prevent focus from moving out of the trapped region due to mouse
interaction.
Regions
Regions can be declared explicitly with an initial focus element by using
the cdkFocusRegionStart, cdkFocusRegionEnd and cdkFocusInitial DOM attributes. cdkFocusInitial specifies the element that will receive focus upon initialization of the region. cdkFocusRegionStart and cdkFocusRegionEnd define the region within which focus will be
trapped. When using the tab key, focus will move through this region and wrap around on either end.
For example:
<amat-list-itemrouterLinkcdkFocusRegionStart>Focus region start</a><amat-list-itemrouterLink>Link</a><amat-list-itemrouterLinkcdkFocusInitial>Initially focused</a><amat-list-itemrouterLinkcdkFocusRegionEnd>Focus region end</a>
InteractivityChecker
InteractivityChecker is used to check the interactivity of an element, capturing disabled,
visible, tabbable, and focusable states for accessibility purposes. See the API docs for more
details.
LiveAnnouncer
LiveAnnouncer is used to announce messages for screen-reader users using an aria-live region.
See the W3C's WAI-ARIA
for more information on aria-live regions.
The FocusMonitor is an injectable service that can be used to listen for changes in the focus
state of an element. It's more powerful than just listening for focus or blur events because it
tells you how the element was focused (via mouse, keyboard, touch, or programmatically). It also
allows listening for focus on descendant elements if desired.
To listen for focus changes on an element, use the monitor method which takes an element to
monitor and an optional boolean flag checkChildren. Passing true for checkChildren will tell the FocusMonitor to consider the element focused if any of its descendants are focused. This option
defaults to false if not specified. The monitor method will return an Observable that emits the FocusOrigin whenever the focus state changes. The FocusOrigin will be one of the following:
'mouse' indicates the element was focused with the mouse
'keyboard' indicates the element was focused with the keyboard
'touch' indicates the element was focused by touching on a touchscreen
'program' indicates the element was focused programmatically
null indicates the element was blurred
In addition to emitting on the observable, the FocusMonitor will automatically apply CSS classes
to the element when focused. It will add .cdk-focused if the element is focused and will further
add .cdk-${origin}-focused (with ${origin} being mouse, keyboard, touch, or program) to
indicate how the element was focused.
Note: currently the FocusMonitor emits on the observable outside of the Angular zone. Therefore
if you markForCheck in the subscription you must put yourself back in the Angular zone.
Any element that is monitored by calling monitor should eventually be unmonitored by calling stopMonitoring with the same element.
It is possible to falsify the FocusOrigin when setting the focus programmatically by using the focusVia method of FocusMonitor. This method accepts an element to focus and the FocusOrigin
to use. If the element being focused is currently being monitored by the FocusMonitor it will
report the FocusOrigin that was passed in. If the element is not currently being monitored it will
just be focused like normal.
cdkMonitorElementFocus and cdkMonitorSubtreeFocus
For convenience, the CDK also provides two directives that allow for easily monitoring an element. cdkMonitorElementFocus is the equivalent of calling monitor on the host element with checkChildren set to false. cdkMonitorSubtreeFocus is the equivalent of calling monitor on
the host element with checkChildren set to true. Each of these directives has an @Output() cdkFocusChange that will emit the new FocusOrigin whenever it changes.
The text was updated successfully, but these errors were encountered:
The
a11y
package provides a number of tools to improve accessibility, described below.ListKeyManager
ListKeyManager
manages the active option in a list of items based on keyboard interaction.Intended to be used with components that correspond to a
role="menu"
orrole="listbox"
pattern.Basic usage
Any component that uses a
ListKeyManager
will generally do three things:@ViewChildren
query for the options being managed.ListKeyManager
, passing in the options.ListKeyManager
.Each option should implement the
ListKeyManagerOption
interface:Wrapping
Navigation through options can be made to wrap via the
withWrap
methodTypes of key managers
There are two varieties of
ListKeyManager
,FocusKeyManager
andActiveDescendantKeyManager
.FocusKeyManager
Used when options will directly receive browser focus. Each item managed must implement the
FocusableOption
interface:ActiveDescendantKeyManager
Used when options will be marked as active via
aria-activedescendant
.Each item managed must implement the
Highlightable
interface:Each item must also have an ID bound to the listbox's or menu's
aria-activedescendant
.FocusTrap
The
cdkTrapFocus
directive traps Tab key focus within an element. This is intended tobe used to create accessible experience for components like
modal dialogs, where focus must be
constrained.
This directive is declared in
A11yModule
.Example
This directive will not prevent focus from moving out of the trapped region due to mouse
interaction.
Regions
Regions can be declared explicitly with an initial focus element by using
the
cdkFocusRegionStart
,cdkFocusRegionEnd
andcdkFocusInitial
DOM attributes.cdkFocusInitial
specifies the element that will receive focus upon initialization of the region.cdkFocusRegionStart
andcdkFocusRegionEnd
define the region within which focus will betrapped. When using the tab key, focus will move through this region and wrap around on either end.
For example:
InteractivityChecker
InteractivityChecker
is used to check the interactivity of an element, capturing disabled,visible, tabbable, and focusable states for accessibility purposes. See the API docs for more
details.
LiveAnnouncer
LiveAnnouncer
is used to announce messages for screen-reader users using anaria-live
region.See the W3C's WAI-ARIA
for more information on aria-live regions.
Example
FocusMonitor
The
FocusMonitor
is an injectable service that can be used to listen for changes in the focusstate of an element. It's more powerful than just listening for
focus
orblur
events because ittells you how the element was focused (via mouse, keyboard, touch, or programmatically). It also
allows listening for focus on descendant elements if desired.
To listen for focus changes on an element, use the
monitor
method which takes an element tomonitor and an optional boolean flag
checkChildren
. Passing true forcheckChildren
will tell theFocusMonitor
to consider the element focused if any of its descendants are focused. This optiondefaults to
false
if not specified. Themonitor
method will return an Observable that emits theFocusOrigin
whenever the focus state changes. TheFocusOrigin
will be one of the following:'mouse'
indicates the element was focused with the mouse'keyboard'
indicates the element was focused with the keyboard'touch'
indicates the element was focused by touching on a touchscreen'program'
indicates the element was focused programmaticallynull
indicates the element was blurredIn addition to emitting on the observable, the
FocusMonitor
will automatically apply CSS classesto the element when focused. It will add
.cdk-focused
if the element is focused and will furtheradd
.cdk-${origin}-focused
(with${origin}
beingmouse
,keyboard
,touch
, orprogram
) toindicate how the element was focused.
Note: currently the
FocusMonitor
emits on the observable outside of the Angular zone. Thereforeif you
markForCheck
in the subscription you must put yourself back in the Angular zone.Any element that is monitored by calling
monitor
should eventually be unmonitored by callingstopMonitoring
with the same element.It is possible to falsify the
FocusOrigin
when setting the focus programmatically by using thefocusVia
method ofFocusMonitor
. This method accepts an element to focus and theFocusOrigin
to use. If the element being focused is currently being monitored by the
FocusMonitor
it willreport the
FocusOrigin
that was passed in. If the element is not currently being monitored it willjust be focused like normal.
cdkMonitorElementFocus and cdkMonitorSubtreeFocus
For convenience, the CDK also provides two directives that allow for easily monitoring an element.
cdkMonitorElementFocus
is the equivalent of callingmonitor
on the host element withcheckChildren
set tofalse
.cdkMonitorSubtreeFocus
is the equivalent of callingmonitor
onthe host element with
checkChildren
set totrue
. Each of these directives has an@Output()
cdkFocusChange
that will emit the newFocusOrigin
whenever it changes.The text was updated successfully, but these errors were encountered: