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 (keydown, keypress, or keyup) identifies what kind of keyboard activity occurred.

Note: KeyboardEvent events 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 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.

Constructor

KeyboardEvent()
Creates a new KeyboardEvent object.

Methods

This interface also inherits methods of its parents, UIEvent and Event.

KeyboardEvent.getModifierState()
Returns a Boolean indicating if a modifier key such as Alt, Shift, Ctrl, or Meta, was pressed when the event was created.
KeyboardEvent.initKeyEvent()
Initializes a KeyboardEvent object. This was implemented only by Firefox, and is no longer supported even there; instead, you should use the KeyboardEvent() constructor.
KeyboardEvent.initKeyboardEvent()
Initializes a KeyboardEvent object. This is now deprecated. You should instead use the KeyboardEvent() constructor.

Properties

This interface also inherits properties of its parents, UIEvent and Event.

KeyboardEvent.altKey Read only
Returns a Boolean that is true if the Alt ( Option or on OS X) key was active when the key event was generated.
KeyboardEvent.char Read only
Returns a DOMString representing the character value of the key. If the key corresponds to a printable character, this value is a non-empty Unicode string containing that character. If the key doesn't have a printable representation, this is an empty string.
Note: If the key is used as a macro that inserts multiple characters, this attribute's value is the entire string, not just the first character.
KeyboardEvent.charCode Read only
Returns a Number representing the Unicode reference number of the key; this attribute is used only by the keypress event. For keys whose char attribute contains multiple characters, this is the Unicode value of the first character in that attribute. In Firefox 26 this returns codes for printable characters.
Warning: This attribute is deprecated; you should use KeyboardEvent.key instead, if available.
KeyboardEvent.code Read only
Returns a DOMString 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").
KeyboardEvent.ctrlKey Read only
Returns a Boolean that is true if the Ctrl key was active when the key event was generated.
KeyboardEvent.isComposing Read only
Returns a Boolean that is true if the event is fired between after compositionstart and before compositionend.
KeyboardEvent.key Read only
Returns a DOMString representing the key value of the key represented by the event.
KeyboardEvent.keyCode Read only
Returns a Number representing a system and implementation dependent numerical code identifying the unmodified value of the pressed key.
Warning: This attribute is deprecated; you should use KeyboardEvent.key instead, if available.
KeyboardEvent.keyIdentifier Read only
This property is non-standard and has been deprecated in favor of KeyboardEvent.key. It was part of an old version of DOM Level 3 Events.
KeyboardEvent.keyLocation Read only
This is a non-standard deprecated alias for KeyboardEvent.location. It was part of an old version of DOM Level 3 Events.
KeyboardEvent.locale Read only
Returns a DOMString representing a locale string indicating the locale the keyboard is configured for. This may be the empty string if the browser or device doesn't know the keyboard's locale.
Note: This does not describe the locale of the data being entered. A user may be using one keyboard layout while typing text in a different language.
KeyboardEvent.locationRead only
Returns a Number representing the location of the key on the keyboard or other input device.
KeyboardEvent.metaKey Read only
Returns a Boolean that is true if the Meta key (on Mac keyboards, the ⌘ Command key; on Windows keyboards, the Windows key ()) was active when the key event was generated.
KeyboardEvent.repeat Read only
Returns a Boolean that is true if the key is being held down such that it is automatically repeating.
KeyboardEvent.shiftKey Read only
Returns a Boolean that is true if the Shift key was active when the key event was generated.
KeyboardEvent.which Read only
Returns a Number representing a system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same as keyCode.
Warning: This attribute is deprecated; you should use KeyboardEvent.key instead, if available.

Usage notes

There are three types of keyboard events: keydown, keypress, and keyup. For most keys, Gecko dispatches a sequence of key events like this:

  1. When the key is first depressed, the keydown event is sent.
  2. If the key is not a modifier key, the keypress event is sent.
  3. When the user releases the key, the keyup event is sent.

Special cases

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.

On Linux, Firefox 12 and earlier also dispatched the keypress event 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 bug 602812.

Auto-repeat handling

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:

  1. keydown
  2. keypress
  3. keydown
  4. keypress
  5. <<repeating until the user releases the key>>
  6. keyup

This is what the DOM Level 3 specification says should happen. There are some caveats, however, as described below.

Auto-repeat on some GTK environments such as Ubuntu 9.4

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 keypresses and an auto-repeat. On those platforms, then, an auto-repeat key will generate the following sequence of events:

  1. keydown
  2. keypress
  3. keyup
  4. keydown
  5. keypress
  6. keyup
  7. <<repeating until the user releases the key>>
  8. keyup

In 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.

Auto-repeat handling prior to Gecko 5.0

Before Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), keyboard handling was less consistent across platforms.

Windows
Auto-repeat behavior is the same as in Gecko 4.0 and later.
Mac
After the initial keydown event, only keypress events are sent until the keyup event occurs; the inter-spaced keydown events are not sent.
Linux
The event behavior depends on the specific platform. It will either behave like Windows or Mac depending on what the native event model does.

Note: Manually firing an event does not generate the default action associated with that event. For example, manually firing a key event does not cause that letter to appear in a focused text input. In the case of UI events, this is important for security reasons, as it prevents scripts from simulating user actions that interact with the browser itself.

Example

<!DOCTYPE html>
<html>
<head>
<script>
'use strict';

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}`);
  }
}, false);

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');
  }
}, false);

</script>
</head>

<body>
</body>
</html>

Specifications

Specification Status Comment
UI Events
The definition of 'KeyboardEvent' in that specification.
Working Draft  

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, KeyboardEvent.initKeyboardEvent() by others. Both have been superseded by the modern usage of a constructor: KeyboardEvent().

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
Basic supportChrome Full support YesEdge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android ?
KeyboardEventChrome Full support YesEdge ? Firefox Full support 31IE No support NoOpera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile ? Firefox Android Full support 31Opera Android Full support YesSafari iOS ? Samsung Internet Android ?
altKeyChrome Full support YesEdge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android ? Chrome Android ? Edge Mobile Full support YesFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
charCode
DeprecatedNon-standard
Chrome Full support 26Edge Full support YesFirefox Full support 3IE Full support 9Opera Full support 12.1Safari Full support 5.1WebView Android ? Chrome Android ? Edge Mobile Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support 5.1Samsung Internet Android ?
codeChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
ctrlKeyChrome Full support YesEdge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android ? Chrome Android ? Edge Mobile Full support YesFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
isComposingChrome Full support 56Edge ? Firefox Full support 31IE No support NoOpera Full support 43Safari No support NoWebView Android Full support 56Chrome Android Full support 56Edge Mobile ? Firefox Android Full support 31Opera Android Full support 43Safari iOS No support NoSamsung Internet Android ?
keyChrome Full support 51Edge Full support YesFirefox Full support 23IE Full support 9
Notes
Full support 9
Notes
Notes IE's impementation does not completely match the current spec because it is based on an older version of the spec.
Opera Full support 38Safari Full support YesWebView Android Full support 51Chrome Android Full support 51Edge Mobile Full support YesFirefox Android Full support 23Opera Android Full support 38Safari iOS Full support YesSamsung Internet Android ?
keyCode
DeprecatedNon-standard
Chrome Full support 26Edge Full support YesFirefox Full support 3IE Full support 6Opera Full support 11.6Safari Full support 5WebView Android ? Chrome Android ? Edge Mobile Full support YesFirefox Android ? Opera Android ? Safari iOS Full support 5.1Samsung Internet Android ?
keyIdentifier
DeprecatedNon-standard
Chrome No support 26 — 54Edge ? Firefox No support NoIE No support NoOpera No support 15 — 41Safari Full support 5.1WebView Android No support ? — 54Chrome Android No support 26 — 54Edge Mobile ? Firefox Android No support NoOpera Android No support ? — 41Safari iOS Full support 5.1Samsung Internet Android ?
locationChrome Full support YesEdge Full support YesFirefox Full support 15IE Full support 9Opera Full support YesSafari Full support 6.1WebView Android ? Chrome Android ? Edge Mobile Full support YesFirefox Android Full support 15Opera Android ? Safari iOS Full support 8Samsung Internet Android ?
metaKeyChrome Full support YesEdge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android ? Chrome Android ? Edge Mobile Full support YesFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
repeatChrome Full support YesEdge No support NoFirefox Full support 28IE No support NoOpera ? Safari Full support 10.1WebView Android ? Chrome Android ? Edge Mobile No support NoFirefox Android Full support 28Opera Android ? Safari iOS Full support 10.1Samsung Internet Android ?
shiftKeyChrome Full support YesEdge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android ? Chrome Android ? Edge Mobile Full support YesFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
which
DeprecatedNon-standard
Chrome Full support 4Edge Full support YesFirefox Full support 2
Notes
Full support 2
Notes
Notes Firefox also implements this property on the UIEvent interface.
IE Full support 9Opera Full support 10.1Safari Full support 5.1WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support Yes
Notes
Full support Yes
Notes
Notes Firefox also implements this property on the UIEvent interface.
Opera Android ? Safari iOS Full support 5.1Samsung Internet Android ?
getModifierStateChrome Full support 31Edge Full support YesFirefox Full support 15IE Full support 9Opera Full support 17Safari Full support 10.1WebView Android Full support 4.4.3Chrome Android Full support 31Edge Mobile Full support YesFirefox Android Full support 15Opera Android No support NoSafari iOS Full support 10.3Samsung Internet Android Full support Yes
DOM_KEY_LOCATION_LEFTChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
DOM_KEY_LOCATION_NUMPADChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
DOM_KEY_LOCATION_RIGHTChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?
DOM_KEY_LOCATION_STANDARDChrome ? Edge ? Firefox ? IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android ?

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.
Deprecated. Not for use in new websites.
Deprecated. Not for use in new websites.
See implementation notes.
See implementation notes.

See also