Security News
Maven Central Adds Sigstore Signature Validation
Maven Central now validates Sigstore signatures, making it easier for developers to verify the provenance of Java packages.
By Sarah Gooding - Feb 06, 2025
New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
keyboard-simulator
Advanced tools
Keyboard Simulator
A stateful keyboard events dispatcher.
✅ Great for testing your hotkeys and keyboard shortcuts.
On the other side of hotkeys and keyboard shortcuts libraries, which are more about listening to event.key - the generated character of a key, Keyboard-Simulator is more about simulating actual key presses by their physical key IDs (event.code).
In other words: it's not about the $, it's about the ShiftLeft and Digit4.
Don't worry, there are key aliases like
shiftand4.
See the Key List below.
Keyboard-Simulator aims to mimick a real keyboard behavior by keeping track of its key activation and dispatching keyboard events that are shaped according to the different states of meaningful keyboard's keys like CapsLock.
Key features:
- The dispatching element updates dynamically as DOM focus changes (
document.activeElement) - The value of
event.keytakes into account:NumLockstateCapsLockstate (for letters)Shiftstate (for letters, number and symbols)
Note:
NumLockis on by default.CapsLockandScrollLockare off. - The following event properties are set according to the modifier keys that are pressed down:
event.ctrlKeyevent.altKeyevent.shiftKeyevent.metaKey
- The following event properties are set with defaults:
event.bubbles = trueevent.cancelable = trueevent.composed = trueevent.repeat = falseevent.isComposing = falseevent.view = Windowevent.location = 1
- Pressing an already-down key throws an error.
- Releasing a non-pressed key throws an error.
Currently only supports EN-US Qwerty keyboard layout.
Install
$ npm install keyboard-simulator
Basic Usage
import {KeyboardSimulator} from 'keyboard-simulator`;
const kbSim = new KeyboardSimulator();
kbSim.keyDown('A');
kbSim.keyUp('A');
// or:
kbSim.keyPress('A');
kbSim.keyDown('Ctrl', 'B');
keyDown.release();
// or:
kbSim.Combine('Ctrl', 'B');
The Dispatching Element
The element that listens to events is the
event.currentTarget.
The element that dispatches events is theevent.target.
When typing, keyboard events are naturally dispatched on the element within focus. On a fresh page load, focus starts on the <body> element until another element, such as an input field, receives focus, either by user interaction (e.g. when clicked on or Tab-navigated into) or programmatically (e.g. input.focus()). Once in focus, all keyboard events will be dispatched on that input element.
The Document object tracks the currently focused element, which can be accessed via document.activeElement. By default, KeyboardSimulator follows this behavior and dispatches keyboard events on the currently active element:
kbSim.keyDown('A');
// --> document.activeElement.dispatchEvent(KeyboardEvent)
When document.activeElement doesn't point to your expected element, make sure that element is:
- "focusable"
- currently has focus.
To enable focus on an "unfocusable" element give it a
tabindex="1"attribute and call.focus()on that element.
See MDN tabindex docs for details.
If you prefer not to use the dynamic behavior of document.activeElement you can override it by setting a static context element. You can do so on construction or by calling the instance's .setContextElm(elm) method.
At any point you can check the current context element with instance.ctxElm
API
Constructor
const instance = new KeyboardSimulator(contextElm);
// or:
const instance = new KeyboardSimulator();
instance.setContextElm(contextElm); // optional
⚠ Non-browser environments: You might need to pass in the runtime's
documentobject as the constructor argument. See details.
contextElm - Optional. HTMLElement | Document
HTMLElement- That element becomes the dispatching element. This overrides the default behavior of a dynamic dispatching element mentioned above.Document- A document is only used for reference. The dispatching element remains dynamic.
Returns a KeyboardSimulator instance that has the following methods:
.keyDown().keyUp().keyPress().combine().repeat().release().setContextElm().ctxElm[Getter].createKeyboardEvent().reset()
See the Key List below.
Non-Browser Environments
The contextElm is also being used internally for referencing the Document object so passing a context might be mandatory when running in non-browser environments (e.g. JSDOM when not configured ideally).
If no context is passed, Document is grabbed from the global scope and that might cause an issue as the library code and your runtime code are using different Document objects. In this case pass the contructor with the document object (it will not be treated as a context element).
If you pass in an HTMLElement you don't need to pass a document, it will be derived from the HTML element via elm.ownerDocument.
.keyDown(...keys)
Dispatches one or more keydown events of given keys.
Returns a boolean (or an array of booleans if passed in multiple keys), which is the result of .dispatchEvent(). MDN dispatchEvent docs.
kbSim.keyDown('A');
kbSim.keyDown('X', 'Y', 'Z');
The instance tries to simulate a real physical keyboard so when a key is already pressed down, trying to press it again throws an error:
kbSim.keyDown('A');
kbSim.keyDown('A'); // ERROR - key 'A' is already pressed down
.keyUp(...keys)
Dispatches one or more keyup events of given keys.
Returns a boolean (or an array of booleans if passed in multiple keys), which is the result of .dispatchEvent(). MDN dispatchEvent docs.
kbSim.keyUp('A');
kbSim.keyUp('X', 'Y', 'Z');
The instance tries to simulate a real physical keyboard so when a key is not pressed down, trying to release it with .keyUp() throws an error:
kbSim.keyDown('A');
kbSim.keyUp('A');
kbSim.keyUp('A'); // ERROR - key 'A' is not pressed down
.keyPress(...keys)
Dispatches a keydown event followed by a keyup event for each given key, like user typing.
Returns a tuple (for a single key) or an array of tuples (for multiple keys). Each tuple is an array of two booleans i.e [true, true]. These booleans are the results of the dispatching of two events of a single keypress, one for the dispatching of keydown and one for keyup. MDN dispatchEvent docs.
kbSim.keyPress('A');
kbSim.keyPress('A', 'B', 'C');
const results = kbSim.keyPress('A', 'B', 'C');
// -> [[true, true], [true, true], [true, true]]
// -> [[A down, up], [B down, up], [C down, up]]
.combine(...keys)
For simulating key combinations (e.g. ctrl-alt-m). First, it dispatches keydown events for all given keys, then dispatches all the keyup events in reverse order (last pressed key is released first).
Returns a tuple of two arrays: the first one is for all the keydown events and the second is for the keyup events (reversed). MDN dispatchEvent docs.
const results = kbSim.combine('Ctrl', 'Alt', 'A');
// -> [[true, true, true], [true, true, true]]
const [keydownResults, keyupResults] = results;
// keydownResults -> [CtrlDown, AltDown, ADown]
// keyupResults -> [AUp, AltUp, CtrlUp]
.repeat(count)
Simulates holding a key down by dispatching multiple keydown events for the last pressed key with the repeat property set to true.
Returns an array of booleans which are the results of .dispatchEvent(). MDN dispatchEvent docs.
kbSim.keyDown('A', 'B', 'C'); // A B C
kbSim.repeat(3); // C C C
.release()
Dispatches keyup events for all the keys that are pressed down in the reverse order in which they were pressed (the first key down is the last to be released).
Return the same results as .keyUp()
NOTE: Can also be used as a
.keyUp()alias.
kbSim.keyDown('A', 'B', 'C');
kbSim.release(); // keyup C, B, A
// or:
kbSim.release('C', 'B', 'A');
.setContextElm(HTMLElement)
Sets an element as the dispatching element. Once a context element is set, the instance will ignore document.activeElement.
Call with no arguments to unset the context element. The instance will dispatch on document.activeElement again.
const kbSim = new KeyboardSimulator();
// document.activeElement = `<body>` by default
kbSim.keyPress('A'); // ev.target === <body>
input.focus(); // Changes active element
kbSim.keyPress('A'); // ev.target === <input>
kbSim.setContextElm(myDiv); // Overrides active element
input.focus(); // wouldn't matter
kbSim.keyPress('A'); // ev.target === <myDiv>
kbSim.setContextElm(); // Back to activeElement
kbSim.keyPress('A'); // ev.target === <input>
Note: Calling
.reset()removes the context element.
.ctxElm - [Getter]
Returns the current dispathing element.
If a context element is set - returns it, else returns document.activeElement.
document.activeElementmight benullin non-browser environments.
const kbSim = new KeyboardSimulator();
// document.activeElement = `<body>` by default
consle.log(kbSim.ctxElm); // -> <body>
input.focus(); // Changes active element
consle.log(kbSim.ctxElm); // -> <input>
kbSim.setContextElm(myDiv);
consle.log(kbSim.ctxElm); // -> <myDiv>
input.focus(); // wouldn't matter
consle.log(kbSim.ctxElm); // -> <myDiv>
kbSim.setContextElm(); // Back to activeElement
consle.log(kbSim.ctxElm); // -> <input>
.createKeyboardEvent(eventType, keyName, eventOpts)
- eventType -
'keydown'|'keyup' - keyName - A key ID or alias (see Key List below)
- eventOpts - Optional.
KeyboardEventInittype. See defaults below or read more on MDN KeyboardEvent docs.
If, for any reason, KeyboardSimulator methods don't support your need, you can create and dispatch your own keyboard event.
eventOpts defaults are:
{
code: ?, // Resolved from `keyName` argument
key: ?, // Resolved from `keyName` argument
ctrlKey: ?, // According to the state of the instance
altKey: ?, // According to the state of the instance
shiftKey: ?, // According to the state of the instance
metaKey: ?, // According to the state of the instance
view: Window, // Resolved from the context element or from the environment
repeat: false,
location: 1,
bubbles: true,
cancelable: true,
composed: true,
isComposing: false,
}
const kbEvent = kbSim.createKeyboardEvent('keydown', 'A', {bubbles: false});
kbSim.ctxElm.dispatchEvent(kbEvent);
.reset()
The instance keeps track of pressed keys. Calling .reset() clears the records, context element included.
NOTE:
.reset()does not clear thedocumentreference.
kbSim.keyDown('A');
kbSim.keyDown('A'); // ERROR - key 'A' is already pressed down
kbSim.reset();
kbSim.keyDown('A'); // OK
Keys
The Keyboard Simulator instance's methods expect a KeyName type or an array of them.
KeyName could be either a standard key ID (ev.code) or an alias, provided by Keyboard Simulator.
A key ID is like an identifier of a specific physical key on a keyboad. Aliases are just for sugar.
For example, there is no such key as Control, there are only ControlLeft and ControlRight key IDs. Control is their common generated value.
That said, using key aliases you can use Control or Ctrl. Both are mapped to ControlLeft.
Keys List
NOTE:
Key IDs are case sensitive. Aliases are not.
Not all keys have aliases.
| Key ID | Aliases |
|---|---|
| KeyA | A |
| KeyB | B |
| KeyC | C |
| KeyD | D |
| KeyE | E |
| KeyF | F |
| KeyG | G |
| KeyH | H |
| KeyI | I |
| KeyJ | J |
| KeyK | K |
| KeyL | L |
| KeyM | M |
| KeyN | N |
| KeyO | O |
| KeyP | P |
| KeyQ | Q |
| KeyR | R |
| KeyS | S |
| KeyT | T |
| KeyU | U |
| KeyV | V |
| KeyW | W |
| KeyX | X |
| KeyY | Y |
| KeyZ | Z |
| Digit0 | 0 |
| Digit1 | 1 |
| Digit2 | 2 |
| Digit3 | 3 |
| Digit4 | 4 |
| Digit5 | 5 |
| Digit6 | 6 |
| Digit7 | 7 |
| Digit8 | 8 |
| Digit9 | 9 |
| Numpad0 | Np0 |
| Numpad1 | Np1 |
| Numpad2 | Np2 |
| Numpad3 | Np3 |
| Numpad4 | Np4 |
| Numpad5 | Np5 |
| Numpad6 | Np6 |
| Numpad7 | Np7 |
| Numpad8 | Np8 |
| Numpad9 | Np9 |
| NumpadDecimal | Decimal |
| NumpadDivide | Divide |
| NumpadSubtract | Subtract |
| NumpadMultiply | Multiply |
| NumpadAdd | Add |
| ArrowUp | Up |
| ArrowRight | Right |
| ArrowDown | Down |
| ArrowLeft | Left |
| PageUp | PgUp |
| PageDown | PgDn |
| Home | |
| End | |
| ControlLeft | Ctrl / Control / LCtrl |
| ControlRight | RCtrl |
| AltLeft | Alt / LAlt |
| AltRight | RAlt |
| ShiftLeft | Shift / LShift |
| ShiftRight | RShift |
| MetaLeft | Meta / LMeta |
| MetaRight | RMeta |
| Slash | |
| Backslash | |
| IntlBackslash | |
| Period | |
| Comma | |
| Quote | SingleQuote |
| Backquote | BackTick |
| Semicolon | |
| BracketLeft | |
| BracketRight | |
| Minus | |
| Equal | |
| Enter | |
| NumpadEnter | NpEnter / REnter |
| Space | |
| Backspace | |
| Tab | |
| Delete | Del |
| Insert | Ins |
| Pause | |
| PrintScreen | |
| ScrollLock | |
| NumLock | |
| CapsLock | |
| ContextMenu | |
| Escape | Esc |
| F1 | |
| F2 | |
| F3 | |
| F4 | |
| F5 | |
| F6 | |
| F7 | |
| F8 | |
| F9 | |
| F10 | |
| F11 | |
| F12 | |
| F13 | |
| F14 | |
| F15 | |
| F16 | |
| F17 | |
| F18 | |
| F19 | |
| F20 | |
| F21 | |
| F22 | |
| F23 | |
| F24 |
FAQs
A smart keyboard events dispatcher.
The npm package keyboard-simulator receives a total of 0 weekly downloads. As such, keyboard-simulator popularity was classified as not popular.
We found that keyboard-simulator demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Package last updated on 23 Jan 2025
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Related posts
Security News
38% of CISOs Fear They’re Not Moving Fast Enough on AI
CISOs are racing to adopt AI for cybersecurity, but hurdles in budgets and governance may leave some falling behind in the fight against cyber threats.
By Sarah Gooding - Feb 04, 2025
Research
Security News
Go Supply Chain Attack: Malicious Package Exploits Go Module Proxy Caching for Persistence
Socket researchers uncovered a backdoored typosquat of BoltDB in the Go ecosystem, exploiting Go Module Proxy caching to persist undetected for years.
By Kirill Boychenko - Feb 04, 2025