What’s New with KeyboardEvents? Keys and Codes!

The past few versions of Chrome have seen two additions to KeyboardEvents, which are used as a parameter passed to keydown, keypress, and keyup event listeners. Both the code attribute (added in Chrome 48) and the key attribute (added in Chrome 51) give developers a straightforward way to get information that would otherwise be difficult using legacy attributes.

The code attribute

First up is the code attribute. This is set to a string representing the key that was pressed to generate the KeyboardEvent, without taking the current keyboard layout (for example, QWERTY vs. Dvorak), locale (for example, English vs. French), or any modifier keys into account. This is useful when you care about which physical key was pressed, rather thanwhich character it corresponds to. For example, if you’re a writing a game, you might want a certain set of keys to move the player in different directions, and that mapping should ideally be independent of keyboard layout.

The key attribute

Next, we have the new key attribute. It’s also set to a string, but while code returns information about the physical key that was pressed, key contains the character that is generated by that key, taking into account the current keyboard layout, locale and modifier keys. Looking at the key attribute’s value comes in handy when you need to know what character would be displayed on the screen as if the user had typed into a text input.

What’s this mean in practice?

To give a concrete example, let’s assume your user is using a U.S. keyboard with a QWERTY keyboard layout. Pressing the physical Q key on that keyboard will result in a KeyboardEvent with a code attribute set to "KeyQ". This is true regardless of keyboard layout, and regardless of any other modifier keys. For comparison, on a French (AZERTY) keyboard this key would still have a code of "KeyQ" even though the letter printed on the keycap is an "a". Pressing the physical Q key on that same U.S. keyboard will typically generate a KeyboardEvent with key set to "q" (with no modifier keys), or "Q" (with Shift or CapsLock), or "œ" (on OS X, with Alt). On a French AZERTY keyboard, this same key would generate an "a" (or "A" with Shift or CapsLock). And for other keyboard layouts, the key value could be "й", "ض", "ㅂ", "た", or some other character. Revisiting our game example from earlier, if you want your game to use the WASD keys for movement, you can use the code attribute and check for "KeyW", "KeyA", "KeyS" and "KeyD". This will work for all keyboards and all layouts—even AZERTY keyboards that swap the position of the "w" and "z" keys.

Virtual keyboards

You’ll notice that up until now, we’ve been focusing on the behavior assuming a physical keyboard. What about users who are typing on a virtual keyboard or an alternative input device? The specification offers official guidance for the code attribute. To summarize, a virtual keyboard that mimics the layout of a standard keyboard is expected to result in an appropriate code attribute being set, but virtual keyboards that adopt non-traditional layouts may result in code not being set at all.

Things are more straightforward for the key attribute, which you should expect to be set to a string based on which character the user (virtually) typed.

Try it out

Gary Kačmarčík has put together a fantastic demo for visualizing all the attributes associated with KeyboardEvents:

Cross-browser support

Support for the code attribute is, as of this writing, limited to Chrome 48+, Opera 35+, and Firefox 44+. The key attribute is supported in Firefox 44+, Chrome 51+, and Opera 38+, with partial support in Internet Explorer 9+ and Edge 13+.