Class A11yHelper
Constructors
constructor
- new A11yHelper(): A11yHelper
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
- applyFocusSource(
options: A11yFocusSource | { focusSource: A11yFocusSource },
): void 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,
): FocusableElement Returns 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;
},
): A11yFocusSource Gets 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.
See
- https://bugzilla.mozilla.org/show_bug.cgi?id=1426671
- https://bugzilla.mozilla.org/show_bug.cgi?id=314314
TODO: Evaluate / test against touch input devices.
- options: {
StaticgetLastFocusableElement
- getLastFocusableElement(
element?: Element | Document,
options?: FocusableElementOptions,
): FocusableElement Returns 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, any, any>;
},
): boolean Tests if the given element is focusable.
Parameters
Returns boolean
Element is focusable.
StaticisFocusSource
StaticisFocusTarget
StaticisFocusWithin
- isFocusWithin(element: Element): boolean
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
- isParentHidden(element: Element, stopElement?: Element): boolean
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.