Skip to content
Tutorials Center
My learning

Topics

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.

JSX
<input onKeyDown={(e) => {
  if (e.key === 'Escape') e.currentTarget.blur();
}} />

Try it

Inspect the keys you press
Enter adds, Escape clears

Syntax

JSX
<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 onKeyDown on a container to handle keys for a whole widget, for example arrow-key navigation inside a menu. Use e.target to see which child had focus.
  • Only focused elements receive keys. A plain <div> gets keyboard events only if it has a tabIndex. Global shortcuts need a keydown listener on window or document, added in an effect and removed in its cleanup.
  • Prefer key and code over keyCode. keyCode, charCode and which are deprecated and inconsistent.
  • onKeyPress is deprecated. It still exists in React but browsers no longer standardize it, and it does not fire for keys like Escape or the arrows. Use onKeyDown.
  • Respect IME input. While someone is composing text, Enter confirms the composition. Check isComposing before 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; adding onClick is usually enough.
  • Case matters. With Shift held, key is "A", not "a". Normalize with e.key.toLowerCase() when you compare letters.
  • Controlled inputs. To change what is typed, use onChange, not onKeyDown. Keys are not the same as input (paste, drag, voice, and mobile keyboards all change a field).