files/en-us/web/api/keyboardevent/index.md
{{APIRef("UI Events")}}
KeyboardEvent objects describe a user interaction with the keyboard; each event describes a single interaction between the user and a key (or combination of a key with modifier keys) on the keyboard. The event type ({{domxref("Element/keydown_event", "keydown")}}, {{domxref("Element/keypress_event", "keypress")}}, or {{domxref("Element/keyup_event", "keyup")}}) identifies what kind of keyboard activity occurred.
[!NOTE]
KeyboardEventevents just indicate what interaction the user had with a key on the keyboard at a low level, providing no contextual meaning to that interaction. When you need to handle text input, use the {{domxref("Element/input_event", "input")}} event instead. Keyboard events may not be fired if the user is using an alternate means of entering text, such as a handwriting system on a tablet or graphics tablet.
{{InheritanceDiagram}}
KeyboardEvent object.The KeyboardEvent interface defines the following constants.
The following constants identify which part of the keyboard the key event originates from. They are accessed as KeyboardEvent.DOM_KEY_LOCATION_STANDARD and so forth.
This interface also inherits properties of its parents, {{domxref("UIEvent")}} and {{domxref("Event")}}.
{{domxref("KeyboardEvent.altKey")}} {{ReadOnlyInline}}
true if the <kbd>Alt</kbd> (<kbd>Option</kbd> or <kbd>⌥</kbd> on macOS) key was active when the key event was generated.{{domxref("KeyboardEvent.code")}} {{ReadOnlyInline}}
: Returns a string with the code value of the physical key represented by the event.
[!WARNING] This ignores the user's keyboard layout, so that if the user presses the key at the "Y" position in a QWERTY keyboard layout (near the middle of the row above the home row), this will always return "KeyY", even if the user has a QWERTZ keyboard (which would mean the user expects a "Z" and all the other properties would indicate a "Z") or a Dvorak keyboard layout (where the user would expect an "F"). If you want to display the correct keystrokes to the user, you can use {{domxref("Keyboard.getLayoutMap()")}}.
{{domxref("KeyboardEvent.ctrlKey")}} {{ReadOnlyInline}}
true if the <kbd>Ctrl</kbd> key was active when the key event was generated.{{domxref("KeyboardEvent.isComposing")}} {{ReadOnlyInline}}
true if the event is fired between after compositionstart and before compositionend.{{domxref("KeyboardEvent.key")}} {{ReadOnlyInline}}
{{domxref("KeyboardEvent.location")}} {{ReadOnlyInline}}
{{domxref("KeyboardEvent.metaKey")}} {{ReadOnlyInline}}
true if the <kbd>Meta</kbd> key (on Mac keyboards, the <kbd>⌘ Command</kbd> key; on Windows keyboards, the Windows key (<kbd>⊞</kbd>)) was active when the key event was generated.{{domxref("KeyboardEvent.repeat")}} {{ReadOnlyInline}}
true if the key is being held down such that it is automatically repeating.{{domxref("KeyboardEvent.shiftKey")}} {{ReadOnlyInline}}
true if the <kbd>Shift</kbd> key was active when the key event was generated.{{domxref("KeyboardEvent.charCode")}} {{Deprecated_inline}} {{ReadOnlyInline}}
keypress event. For keys whose char property contains multiple characters, this is the Unicode value of the first character in that property. In Firefox 26 this returns codes for printable characters.{{domxref("KeyboardEvent.keyCode")}} {{deprecated_inline}} {{ReadOnlyInline}}
{{domxref("KeyboardEvent.keyIdentifier")}} {{Non-standard_inline}} {{deprecated_inline}} {{ReadOnlyInline}}
This interface also inherits methods of its parents, {{domxref("UIEvent")}} and {{domxref("Event")}}.
KeyboardEvent object. This is now deprecated. You should instead use the {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} constructor.The following events are based on the KeyboardEvent type. In the list below, each event links to the documentation for the Element handler for the event, which applies generally to all of the recipients, including {{domxref("Element")}}, {{domxref("Document")}}, and {{domxref("Window")}}.
There are three types of keyboard events: {{domxref("Element/keydown_event", "keydown")}}, {{domxref("Element/keypress_event", "keypress")}}, and {{domxref("Element/keyup_event", "keyup")}}. For most keys, Gecko dispatches a sequence of key events like this:
keydown event is sent.keypress event is sent.keyup event is sent.Some keys toggle the state of an indicator light; these include keys such as Caps Lock, Num Lock, and Scroll Lock. On Windows and Linux, these keys dispatch only the keydown and keyup events.
[!NOTE] On Linux, Firefox 12 and earlier also dispatched the
keypressevent for these keys.
However, a limitation of the macOS event model causes Caps Lock to dispatch only the keydown event. Num Lock was supported on some older laptop models (2007 models and older), but since then, macOS hasn't supported Num Lock even on external keyboards. On older MacBooks with a Num Lock key, that key doesn't generate any key events. Gecko does support the Scroll Lock key if an external keyboard which has an F14 key is connected. In certain older versions of Firefox, this key generated a keypress event; this inconsistent behavior was Firefox bug 602812.
When a key is pressed and held down, it begins to auto-repeat. This results in a sequence of events similar to the following being dispatched:
keydownkeypresskeydownkeypresskeyupThis is what the DOM Level 3 specification says should happen. There are some caveats, however, as described below.
In some GTK-based environments, auto-repeat dispatches a native key-up event automatically during auto-repeat, and there's no way for Gecko to know the difference between a repeated series of key presses and an auto-repeat. On those platforms, then, an auto-repeat key will generate the following sequence of events:
keydownkeypresskeyupkeydownkeypresskeyupkeyupIn these environments, unfortunately, there's no way for web content to tell the difference between auto-repeating keys and keys that are just being pressed repeatedly.
document.addEventListener("keydown", (event) => {
const keyName = event.key;
if (keyName === "Control") {
// do not alert when only Control key is pressed.
return;
}
if (event.ctrlKey) {
// Even though event.key is not 'Control' (e.g., 'a' is pressed),
// event.ctrlKey may be true if Ctrl key is pressed at the same time.
alert(`Combination of ctrlKey + ${keyName}`);
} else {
alert(`Key pressed ${keyName}`);
}
});
document.addEventListener("keyup", (event) => {
const keyName = event.key;
// As the user releases the Ctrl key, the key is no longer active,
// so event.ctrlKey is false.
if (keyName === "Control") {
alert("Control key was released");
}
});
{{Specifications}}
The KeyboardEvent interface specification went through numerous draft versions, first under DOM Events Level 2 where it was dropped as no consensus arose, then under DOM Events Level 3. This led to the implementation of non-standard initialization methods, the early DOM Events Level 2 version, KeyboardEvent.initKeyEvent() by Gecko browsers and the early DOM Events Level 3 version, {{domxref("KeyboardEvent.initKeyboardEvent()")}} by others. Both have been superseded by the modern usage of a constructor: {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}.
{{Compat}}
keypress event is no longer fired for non-printable keys (Firefox bug 968056), except for the <kbd>Enter</kbd> key, and the <kbd>Shift</kbd> + <kbd>Enter</kbd> and <kbd>Ctrl</kbd> + <kbd>Enter</kbd> key combinations (these were kept for cross-browser compatibility purposes).