JavaScript Reference ยท DOM: Events
Keyboard events
Reference for keydown, keyup and KeyboardEvent: key vs code, modifier keys, repeat, isComposing, shortcuts, and why keypress is deprecated.
Keyboard input produces two events you should use: keydown, which fires when a key goes down (and again repeatedly while it is held), and keyup, which fires when it is released. Both give you a KeyboardEvent. The old keypress event is deprecated; use keydown or beforeinput/input instead.
Keyboard events go to the element that has focus (or to body when nothing does) and then bubble up. To catch shortcuts anywhere on the page, listen on document.
document.addEventListener("keydown", (event) => { if (event.key === "Escape") closeMenu(); });
Try it
Syntax
element.addEventListener("keydown", (event) => { /* KeyboardEvent */ }); element.addEventListener("keyup", (event) => { /* KeyboardEvent */ });
KeyboardEvent properties
| Property | Description |
|---|---|
key |
The meaning of the key press: "a", "A", "1", "Enter", "Escape", "ArrowLeft", "Tab", " " (space). Depends on layout and modifiers. |
code |
The physical key: "KeyA", "Digit1", "Space", "ArrowLeft". Independent of layout, good for games (WASD). |
repeat |
true if the event is an auto-repeat from a held key. |
shiftKey, ctrlKey, altKey, metaKey |
Whether the modifier was held. |
isComposing |
true while an IME (for example for Chinese or Japanese input) is composing text. |
location |
Which copy of a key it was: 0 standard, 1 left, 2 right, 3 numpad. |
getModifierState(name) |
Reads modifier or lock state, for example "CapsLock". |
Usage notes
keyorcode? Usekeyfor characters and named actions ("Escape"). Usecodewhen position matters, such as game controls, because a French keyboard sends"KeyA"for the key labeled Q.- Legacy properties.
keyCode,whichandcharCodeare deprecated. Do not use them. - Input fields. To react to the text that was entered, use the
inputevent; it also covers paste, drag, voice and virtual keyboards, none of which are reliable with key events. - Do not break typing. Calling
preventDefault()onkeydownblocks the character from appearing. Only do it for keys you handle, and leave shortcuts such as Ctrl+C alone. - IME. Ignore
keydownwhenevent.isComposingistrue, otherwise pressing Enter to confirm a composition may trigger your submit logic. - Shortcuts. Check
ctrlKey || metaKeyto support both Windows/Linux and macOS. Avoid overriding keys the browser or assistive technology uses. - Mobile. Virtual keyboards may report
keyas"Unidentified". Preferinputandbeforeinputfor text. - Auto-repeat. Check
event.repeatwhen an action should run once per press. - Accessibility. Custom widgets need the keyboard behavior users expect: Enter or Space for buttons, arrow keys for lists, Escape to close.
Browser support
keydown, keyup, key and code are supported by all current browsers. Support for keypress still exists but it is deprecated and should not be used in new code.
Related
- input and change events โ react to text changes
- click and pointer events
- focus and blur events โ which element receives keys
Event.preventDefault()- Lesson: Events