React Reference ยท Props and Attributes
React keyboard events (onKeyDown and onKeyUp)
Reference for React keyboard events: onKeyDown and onKeyUp, the key and code properties, modifier keys, repeat, IME composition and why onKeyPress is deprecated.
Keyboard handlers let a component react to keys: submit on Enter, close on Escape, move a selection with the arrow keys. React gives you onKeyDown, which runs when a key goes down (and repeatedly while it is held), and onKeyUp, which runs once when it is released.
The event object tells you which key it was in two ways. event.key is the meaning of the key in the current layout ("a", "A", "Enter", "ArrowDown"). event.code is the physical position ("KeyA", "Enter", "ArrowDown"), the same on every layout. Use key for text-like shortcuts and code for game-style controls such as WASD.
<input onKeyDown={(e) => { if (e.key === 'Escape') e.currentTarget.blur(); }} />
Try it
Syntax
<element onKeyDown={(event: React.KeyboardEvent) => void} onKeyUp={(event: React.KeyboardEvent) => void} />
| Name | Description |
|---|---|
event.key |
The logical key value: a character like "a", or a name like "Enter", "Escape", "Tab", "ArrowLeft", " " (space). |
event.code |
The physical key, such as "KeyA" or "Digit1". Independent of layout and Shift. |
event.shiftKey, ctrlKey, altKey, metaKey |
Whether that modifier is held. metaKey is Command on macOS and the Windows key on Windows. |
event.repeat |
true for the auto-repeat events produced while a key stays held down. |
event.getModifierState(name) |
Reads state of keys such as "CapsLock". |
event.nativeEvent.isComposing |
true while an input method editor is composing text. |
Returns: nothing. Call event.preventDefault() in onKeyDown to stop the browser's default action (typing the character, tabbing away, scrolling on Space).
Usage notes
- Handlers bubble. Put
onKeyDownon a container to handle keys for a whole widget, for example arrow-key navigation inside a menu. Usee.targetto see which child had focus. - Only focused elements receive keys. A plain
<div>gets keyboard events only if it has atabIndex. Global shortcuts need akeydownlistener onwindowordocument, added in an effect and removed in its cleanup. - Prefer
keyandcodeoverkeyCode.keyCode,charCodeandwhichare deprecated and inconsistent. onKeyPressis deprecated. It still exists in React but browsers no longer standardize it, and it does not fire for keys like Escape or the arrows. UseonKeyDown.- Respect IME input. While someone is composing text, Enter confirms the composition. Check
isComposingbefore treating Enter as "submit". - Do not hijack standard keys. Blocking Tab, or capturing Space on a button, breaks keyboard navigation. Native
<button>already handles Enter and Space; addingonClickis usually enough. - Case matters. With Shift held,
keyis"A", not"a". Normalize withe.key.toLowerCase()when you compare letters. - Controlled inputs. To change what is typed, use
onChange, notonKeyDown. Keys are not the same as input (paste, drag, voice, and mobile keyboards all change a field).
Related
- Focus events, Event handlers, The event object, tabIndex
- Lessons: Events, Accessibility