Keycode Inspector: Reading Keyboard Events
After reading this you will know the difference between event.key, event.code and the deprecated keyCode, how modifiers and key location work, and how to write keyboard handlers that survive different layouts.
What a keyboard event actually reports
When you press a key in a browser, JavaScript fires a KeyboardEvent. That event carries several properties describing the press, and they answer different questions. Two of them matter most.
event.code tells you the physical key: the switch under your finger. It does not change when you switch keyboard layouts. The key in the top-left letter row, second from the far left on a US QWERTY board, always reports KeyW, even on a French AZERTY layout where that same physical key produces the letter Z.
event.key tells you the character the layout produces. On QWERTY it gives "w"; on AZERTY the same physical key gives "z". If you hold Shift it gives the uppercase or shifted form: "W", or "%" for a number-row key.
Press the letter Y on both a QWERTY and a German QWERTZ keyboard and you get the same event.code of KeyY, but different event.key values because the two layouts place Y and Z differently. That single fact drives most of the decisions below.
When to reach for code, and when for key
The rule is short. Use event.code when you care about position. Use event.key when you care about meaning.
A game that uses WASD movement wants position, so it reads event.code and matches KeyW, KeyA, KeyS, KeyD. A player on AZERTY presses the same four physical keys in the same triangle shape, and the game still works, even though those keys type Z, Q, S, D.
A text shortcut like "type a question mark to open help" wants meaning, so it reads event.key and checks === "?". It does not care which physical key or which modifier combination produced the character.
Do not test event.keyCode in new code. It is deprecated, and its numeric values are inconsistent across layouts and browsers. The comma key reports 188 in some engines and other numbers elsewhere, and dead keys report differently again. Read key or code instead.
The five fields the inspector shows
The Keycode Inspector reports the values below for each press. Learn what each answers.
- key
- The produced character or named action, such as
"a","A","Enter","ArrowLeft"or"Dead". Layout-dependent and modifier-dependent. - code
- The physical key identifier, such as
KeyA,Digit1,Enter,ShiftLeft,Numpad5. Fixed per physical position. - keyCode
- A legacy integer, such as
65for the A key. Deprecated. Shown only so you can recognise old code. - location
- An integer distinguishing duplicated keys:
0standard,1left,2right,3numpad. Left Shift reports1, right Shift reports2. - modifiers
- Four booleans:
ctrlKey,shiftKey,altKey,metaKey. Each istruewhile that modifier is held during the event.
How the character maps from the physical key
There is no arithmetic formula that converts code to key, because the mapping is a lookup table owned by the operating system layout, not a calculation. You can state the relationship as a function.
Here L is the active layout map. It takes the physical key (code), the Shift state, the AltGr (right Alt) state, and Caps Lock, and returns the character. Because L differs per layout, the same code yields different key values on different machines. The inspector cannot show L directly, but you can probe it: press one physical key with and without Shift, and compare the two key values.
The legacy keyCode for letter keys usually equals the ASCII code of the uppercase letter. The A key gives 65, and A is character 65 in ASCII. The Z key gives 90. This coincidence held for the US layout and broke everywhere else, which is why the value was abandoned.
Reproducing the demo: pressing Shift and A
Load the tool with its defaults and press left Shift, then, while holding it, press the A key on a US QWERTY keyboard. You will see two events.
- The Shift press alone fires a
keydownwithkey = "Shift",code = "ShiftLeft",location = 1, andshiftKey = true. - The A press fires a
keydownwithkey = "A"(uppercase, because Shift is held),code = "KeyA",location = 0, andshiftKey = true. - The legacy
keyCodefor that A press is65regardless of Shift, which is a hint thatkeyCodeignores the produced character.
Release A without Shift and press it again: now key = "a" and shiftKey = false, while code stays KeyA and keyCode stays 65. The physical fields did not move; only the character-level fields did.
Reading modifier combinations correctly
A shortcut like Ctrl+S generates its own sequence. The Ctrl press fires first with ctrlKey still false on that first event in some engines, then true on the S event. Always test the modifier flag on the event for the letter, not on the modifier's own event.
On macOS the Command key sets metaKey, not ctrlKey. If you hardcode ctrlKey, your Save shortcut fails for Mac users, who press Command+S. A portable check treats either as the primary modifier: event.metaKey || event.ctrlKey.
Common mistakes
The errors below account for most broken keyboard handlers.
- Matching letters with
keyCode === 65. It happens to work on US QWERTY and fails on other layouts. Matchevent.code === "KeyA"for position orevent.key === "a"for the letter. - Comparing
event.keywithout Shift in mind. The Escape key gives"Escape", but a shifted number gives a symbol. If you compare against"1"and the user held Shift, they typed"!"and your check misses. - Assuming one event per keypress. Holding a key repeats
keydownevents; checkevent.repeatto skip the repeats. - Ignoring
locationfor numpad handling. The main-row5reportscode = "Digit5",location = 0; the numpad5reportscode = "Numpad5",location = 3.
How events distribute across a typing burst
Type a short word and the inspector history fills with events. A single visible character usually costs one keydown, but capital letters and symbols cost two presses (a modifier plus the key). The chart below counts events for typing the six-character string Hi, ABC including the space, where H and each capital need Shift.
Related tools
Once you know what character a key produced, you often need the next step. If a key produces a symbol you want to place in HTML, the HTML Entity Reference gives its named entity. When you debug which browser and OS a user runs (relevant because macOS maps Command to metaKey), the User-Agent Parser decodes the environment. For visual work on the same Web & CSS pages, the CSS Gradient, Shadow & Radius Generator and the Color Converter & Contrast Checker cover styling.
Frequently asked questions
Why is event.keyCode always the same number when I press Shift plus a letter?
keyCode reports the physical key, not the character, so the A key gives 65 whether or not Shift is held. To detect the uppercase character, read event.key, which returns "A" with Shift and "a" without it.
What is the difference between keydown and keypress?
keypress is deprecated and only fired for character-producing keys. Use keydown for shortcuts and navigation, and use the input event on a field when you care about the resulting text.
How do I tell left Shift from right Shift?
Check event.location: left Shift reports 1, right Shift reports 2. Both share key = "Shift", but their code differs (ShiftLeft versus ShiftRight).
Why does my WASD game break on French keyboards?
You are probably matching event.key. On AZERTY the top-left movement keys produce Z, Q, S, D, not W, A, S, D. Match event.code (KeyW, KeyA, KeyS, KeyD) so the physical triangle of keys works on every layout.
What does key value "Dead" mean?
A dead key is one that combines with the next keystroke to make an accented character, such as pressing the accent key before a vowel. The first press reports key = "Dead" and produces no character on its own; the character appears after the following key.