keydown-key

An utility to normalize the KeyboardEvent.key especially during IME composition

Why need this?

To address the inconsistent behavior of IME across different browsers and platforms:

When selecting a CJK character using the Enter key with IME, the keyDownEvent.key value varies depending on the platform and browser combination.

IME keyDown.key Issue in Chrome on Mac

Example: Screenshot

Differences in keyDown.key Values with IME

• Chrome:

  • Mac: key === "Enter"
  • Windows: key === "Process"

• Firefox:

  • key === "Process" on both Mac and Windows

This discrepancy can cause inconsistencies when handling keyboard events in web applications.

Playground

• [Vanilla JS] https://codepen.io/seawind543/pen/gOWNVYR
• [React JS] https://codepen.io/seawind543/pen/xxdvZyE

Installation

1. Install the latest version of keydown-key:

yarn add keydown-key

2. Apply keydown-key in your application

Example (Vanilla JS)

import keyDownKey from 'keydown-key';

// ... omit

function handleKeyDown(event: KeyboardEvent) { 
  const { key } = keyDownKey(event);

  switch(key) {
    case 'Enter':
      // Do what you want for real `Enter` key
      break;

    case 'Process':
      // The keyDown on "Enter" with IME will be here
      break;

    default: 
  }
}

inputBox.addEventListener('keydown', handleKeyDown);

Example (React JS)

import React from "react";
import keydownKey from "keydown-key";

const handleKeyDown = (event: React.KeyboardEvent) => {
  // use the `nativeEvent` attribute to get the browser KeyboardEvent
  // https://reactjs.org/docs/events.html#overview
  const { key } = keydownKey(event.nativeEvent);

  switch(key) {
    case 'Enter':
      // Do what you want for real `Enter` key
      break;

    case 'Process':
      // The keyDown on "Enter" with IME will be here
      break;

    default: 
  }
};

const App = () => {
  return <input onKeyDown={handleKeyDown} />;
};

export default App;

Reference

[1] IME https://en.wikipedia.org/wiki/Input_method

[2] CJK characters https://en.wikipedia.org/wiki/CJK_characters

[3] add support for SyntheticKeyboardEvent#isComposing facebook/react#13104

[4] Support IME seawind543/react-token-input#1 (comment)

[5] Element: keydown event https://developer.mozilla.org/en-US/docs/Web/API/Document/keydown_event#ignoring_keydown_during_ime_composition

License

MIT