TheKeyboardEvent interface'skey read-only property returns the value of the key pressed by the user, taking into consideration the state of modifier keys such asShift as well as the keyboard locale and layout.

Value

A string.

Its value is determined as follows:

• If the pressed key has a printed representation, the returned value is a non-empty Unicode character string containing the printable representation of the key. For example: if the pressed key is theSpace key, the returned value is a single space (" "). If the pressed key is theB key, the returned value is the string"b". However, if theShift key is pressed at the same time (soshiftKey istrue), the returned value is the string"B".
• If the pressed key is a control or special character, the returned value is one of thepre-defined key values.
• If theKeyboardEvent represents the press of adead key, the key value must be"Dead".
• Some specialty keyboard keys (such as the extended keys for controlling media on multimedia keyboards) don't generate key codes on Windows; instead, they triggerWM_APPCOMMAND events. These events get mapped to DOM keyboard events, and are listed among the "Virtual key codes" for Windows, even though they aren't actually key codes.
• If the key cannot be identified, the returned value isUnidentified.

KeyboardEvent sequence

EveryKeyboardEvent is fired in a pre-determined sequence. For a given key press, the sequence ofKeyboardEvents fired is as follows assuming thatEvent.preventDefault is not called:

1. Akeydown event is first fired. If the key is held down further and the key produces a character key, then the event continues to be emitted in a platform implementation dependent interval and theKeyboardEvent.repeat read only property is set totrue.
2. If the key produces a character key that would result in a character being inserted into possibly an<input>,<textarea> or an element withHTMLElement.contentEditable set to true, thebeforeinput andinput event types are fired in that order. Note that some other implementations may firekeypress event if supported. The events will be fired repeatedly while the key is held down.
3. Akeyup event is fired once the key is released. This completes the process.

In sequence 1 & 3, theKeyboardEvent.key attribute is defined and is set appropriately to a value according to the rules defined earlier.

KeyboardEvent sequence example

Consider the event sequence generated when we interact with theShift and the2 key using a U.S keyboard layout as compared to when we do so using a UK keyboard layout.

Try experimenting using the following two test cases:

1. Press and hold theShift key, then press2 and release it. Next, release theShift key.
2. Press and hold theShift key, then press and hold2. Release theShift key. Finally, release2.

HTML

<div>  <div>    <textarea rows="5" name="test-target"></textarea>    <button type="button" name="btn-reset">Reset</button>  </div>  <div>    <pre></pre>  </div></div>

CSS

.fx {  -webkit-display: flex;  display: flex;  margin-left: -20px;  margin-right: -20px;}.fx > div {  padding-left: 20px;  padding-right: 20px;}.fx > div:first-child {  width: 30%;}.flex {  -webkit-flex: 1;  flex: 1;}#test-target {  display: block;  width: 100%;  margin-bottom: 10px;}

JavaScript

const textarea = document.getElementById("test-target");const consoleLog = document.getElementById("console-log");const btnReset = document.getElementById("btn-reset");function logMessage(message) {  consoleLog.innerText += `${message}\n`;}textarea.addEventListener("keydown", (e) => {  if (!e.repeat) {    logMessage(`Key "${e.key}" pressed [event: keydown]`);  } else {    logMessage(`Key "${e.key}" repeating [event: keydown]`);  }});textarea.addEventListener("beforeinput", (e) => {  logMessage(`Key "${e.data}" about to be input [event: beforeinput]`);});textarea.addEventListener("input", (e) => {  logMessage(`Key "${e.data}" input [event: input]`);});textarea.addEventListener("keyup", (e) => {  logMessage(`Key "${e.key}" released [event: keyup]`);});btnReset.addEventListener("click", (e) => {  let child = consoleLog.firstChild;  while (child) {    consoleLog.removeChild(child);    child = consoleLog.firstChild;  }  textarea.value = "";});

Result

Case 1

When the shift key is pressed, akeydown event is first fired, and thekey property value is set to the stringShift. As we keep holding this key, thekeydown event does not continue to fire repeatedly because it does not produce a character key.

Whenkey 2 is pressed, anotherkeydown event is fired for this new key press, and thekey property value for the event is set to the string@ for the U.S keyboard type and" for the UK keyboard type, because of the active modifiershift key. Thebeforeinput andinput events are fired next because a character key has been produced.

As we release thekey 2, akeyup event is fired and thekey property will maintain the string values@ and" for the different keyboard layouts respectively.

As we finally release theshift key, anotherkeyup event is fired for it, and the key attribute value remainsShift.

Case 2

When the shift key is pressed, akeydown event is first fired, and thekey property value is set to be the stringShift. As we keep holding this key, thekeydown event does not continue to fire repeatedly because it produced no character key.

Whenkey 2 is pressed, anotherkeydown event is fired for this new key press, and thekey property value for the event is set to be the string@ for the U.S keyboard type and" for the UK keyboard type, because of the active modifiershift key. Thebeforeinput andinput events are fired next because a character key has been produced. As we keep holding the key, thekeydown event continues to fire repeatedly and theKeyboardEvent.repeat property is set totrue. Thebeforeinput andinput events are fired repeatedly as well.

As we release theshift key, akeyup event is fired for it, and the key attribute value remainsShift. At this point, notice that thekey property value for the repeating keydown event of thekey 2 key press is now "2" because the modifiershift key is no longer active. The same goes for theInputEvent.data property of thebeforeinput andinput events.

As we finally release thekey 2, akeyup event is fired but thekey property will be set to the string value2 for both keyboard layouts because the modifiershift key is no longer active.

Examples

This example usesEventTarget.addEventListener() to listen forkeydown events. When they occur, the key's value is checked to see if it's one of the keys the code is interested in, and if it is, it gets processed in some way (possibly by steering a spacecraft, perhaps by changing the selected cell in a spreadsheet).

window.addEventListener("keydown", (event) => {  if (event.defaultPrevented) {    return; // Do nothing if the event was already processed  }  switch (event.key) {    case "ArrowDown":      // Do something for "down arrow" key press.      break;    case "ArrowUp":      // Do something for "up arrow" key press.      break;    case "ArrowLeft":      // Do something for "left arrow" key press.      break;    case "ArrowRight":      // Do something for "right arrow" key press.      break;    case "Enter":      // Do something for "enter" or "return" key press.      break;    case " ":      // Do something for "space" key press.      break;    case "Escape":      // Do something for "esc" key press.      break;    default:      return; // Quit when this doesn't handle the key event.  }  // Cancel the default action to avoid it being handled twice  event.preventDefault();});

Specifications

Browser compatibility