Class A11yHelper
Constructors
constructor
Returns A11yHelper
Accessors
Staticdebug
- get debug(): boolean
Returns boolean
Global debugging enabled.
- set debug(debug: boolean): void
Parameters
- debug: boolean
Global debug enabled
Returns void
- debug: boolean
StaticprefersReducedMotion
- get prefersReducedMotion(): boolean
Runs a media query to determine if the user / OS configuration is set up for reduced motion / animation.
Returns boolean
User prefers reduced motion.
Methods
StaticapplyFocusSource
Apply focus to the HTMLElement / SVGElement targets in a given A11yFocusSource data object. An iterable list
options.focusElcan contain HTMLElement / SVGElements or selector strings. If multiple focus targets are provided in a list then the first valid target found will be focused. If focus target is a string then a lookup viadocument.querySelectoris performed. In this case you should provide a unique selector for the desired focus target.Note: The body of this method is postponed to the next clock tick to allow any changes in the DOM to occur that might alter focus targets before applying.
Parameters
- options: A11yFocusSource | { focusSource: A11yFocusSource }
The focus options instance to apply.
Returns void
- options: A11yFocusSource | { focusSource: A11yFocusSource }
StaticgetFirstFocusableElement
- getFirstFocusableElement(
element?: Element | Document,
options?: FocusableElementOptions,
): FocusableElementReturns first focusable element within a specified element.
Parameters
Optionalelement: Element | DocumentOptional element to start query.
Optionaloptions: FocusableElementOptionsOptional parameters.
Returns FocusableElement
First focusable child element.
StaticgetFocusableElements
- getFocusableElements(
element?: Element | Document,
options?: FocusableElementOptions,
): FocusableElement[]Returns all focusable elements within a specified element.
Parameters
Optionalelement: Element | DocumentOptional element to start query.
Optionaloptions: FocusableElementOptionsOptional parameters.
Returns FocusableElement[]
Child keyboard focusable elements.
StaticgetFocusSource
- getFocusSource(
options: {
debug?: boolean;
event?: MouseEvent | KeyboardEvent;
focusEl?: string | FocusableElement;
x?: number;
y?: number;
},
): A11yFocusSourceGets a A11yFocusSource object from the given DOM event allowing for optional X / Y screen space overrides. Browsers (Firefox / Chrome) forwards a mouse event for the context menu keyboard button. Provides detection of when the context menu event is from the keyboard. Firefox as of (1/23) does not provide the correct screen space coordinates, so for keyboard context menu presses coordinates are generated from the centroid point of the element.
A default fallback element or selector string may be provided to provide the focus target. If the event comes from the keyboard however the source focused element is inserted as the target with the fallback value appended to the list of focus targets. When A11yFocusSource is applied by A11yHelper.applyFocusSource the target focus list is iterated through until a connected target is found and focus applied.
Parameters
- options: {
debug?: boolean;
event?: MouseEvent | KeyboardEvent;
focusEl?: string | FocusableElement;
x?: number;
y?: number;
}Options
Optionaldebug?: booleanWhen true A11yHelper.applyFocusSource logs focus target data.
Optionalevent?: MouseEvent | KeyboardEventThe source DOM event.
OptionalfocusEl?: string | FocusableElementA specific HTMLElement / SVGElement or selector string as the focus target.
Optionalx?: numberUsed when an event isn't provided; integer of event source in screen space.
Optionaly?: numberUsed when an event isn't provided; integer of event source in screen space.
Returns A11yFocusSource
A A11yFocusSource object.
- options: {
StaticgetLastFocusableElement
- getLastFocusableElement(
element?: Element | Document,
options?: FocusableElementOptions,
): FocusableElementReturns first focusable element within a specified element.
Parameters
Optionalelement: Element | DocumentOptional element to start query.
Optionaloptions: FocusableElementOptionsOptional parameters.
Returns FocusableElement
Last focusable child element.
StaticisFocusable
- isFocusable(
el: unknown,
options?: { anchorHref?: boolean; ignoreClasses?: Iterable<string> },
): booleanTests if the given element is focusable.
Note: A special case for focus testing occurs when an element has
tabindexof-1and thetjs-a11y-focusableclass.Parameters
Returns boolean
Element is focusable.
StaticisFocusSource
Convenience method to check if the given data is a valid focus source.
Parameters
- data: string | EventTarget | Element
Either an HTMLElement, SVGElement, or selector string.
Returns boolean
Is valid focus source.
- data: string | EventTarget | Element
StaticisFocusTarget
Tests if the given
elementis a Element node and has afocusmethod.Parameters
- element: unknown
Element to test for focus method.
Returns element is FocusableElement
Whether the element has a focus method.
- element: unknown
StaticisFocusWithin
Perform a parent traversal from the current active element attempting to match the given element to test whether current active element is within that element.
Parameters
- element: Element
An element to match in parent traversal from the active element.
Returns boolean
Whether there is focus within the given element.
- element: Element
StaticisParentHidden
Traverses the given element's parent elements to check if any parent has
offsetWidthandoffsetHeightof 0, indicating that a parent element is hidden. If a parent element is hidden, the given element is also considered hidden. This is a reasonably efficient check and can be enabled as a filter step in conjunction with focusable element detection methods like A11yHelper.getFocusableElements.Parameters
Returns boolean
trueif a parent element of the given element is hidden; otherwise,false.
Provides several helpful utility methods for accessibility and keyboard navigation.
Note: Global debugging can be enabled by setting
A11yHelper.debug = true.