@evanminto/keyboard-observer
v1.1.1
Published
JavaScript utility for observing keyboard events fired while a specific element is focused
Downloads
1
Readme
KeyboardObserver
JavaScript utility for observing keyboard events fired while a specific element is focused, with an API inspired by native observers like MutationObserver and ResizeObserver.
Installation
npm install @evanminto/keyboard-observer --save-dev
Usage
// Assuming you're using a module bundler that can resolve Node modules.
import KeyboardObserver from '@evanminto/keyboard-observer';
function keyboardCallback(records) {
records.forEach(record => {
// Do something based on the record's event or target properties.
});
}
// Create the observer (not observing anything yet).
const observer = new KeyboardObserver(keyboardCallback);
const target1 = document.querySelector('#my_element');
const target2 = document.querySelector('#my_element2');
// Start observing a target.
observer.observe(target1);
// You can observe multiple targets at once.
observer.observe(target2);
// Stop observing a single target.
observer.unobserve(target2);
// Stop observing all targets.
observer.disconnect(target2);
Use Cases
Building complex, accessible UI components requires keyboard controls that are
only active when the element has focus. KeyboardObserver
keeps track of this
focus for you, so that your code can respond to only the keyboard events that
are dispatched while the element is actually active.
Full Documentation
KeyboardObserver
Reports keyboard events dispatched while a user is focused on an observed
Element
or SVGElement
.
Methods
KeyboardObserver(callback)
Constructor. Creates and returns new ResizeObserver object.
Parameters
callback: The method called whenever a keyboard event occurs. The method is called with an array of KeyboardRecord
objects.
disconnect()
observe(target, options)
Parameters
target: A reference to an Element
or SVGElement
to be observed.
options: Object
with options for customizing the behavior.
options.penetrateShadowRoots: If false, target matching will only work on light DOM elements, not shadow DOM elements. (Default: true)
unobserve(target)
Parameters
target: A reference to an Element
or SVGElement
to be unobserved.
KeyboardRecord
The object passed to the callback function used in the KeyboardObserver
constructor.
Properties
event: (KeyboardEvent)
target: (Element|SVGElement)