https://github.com/seawind543/keydown-key
An utility to normalize the KeyboardEvent.key especially during IME composition
https://github.com/seawind543/keydown-key
cross-browser cross-platform ime javascript keyboardevent normalize react vanilla-javascript
Last synced: 7 months ago
JSON representation
An utility to normalize the KeyboardEvent.key especially during IME composition
- Host: GitHub
- URL: https://github.com/seawind543/keydown-key
- Owner: seawind543
- License: mit
- Created: 2021-09-04T11:38:07.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-03-04T17:02:00.000Z (10 months ago)
- Last Synced: 2025-06-09T02:12:28.339Z (7 months ago)
- Topics: cross-browser, cross-platform, ime, javascript, keyboardevent, normalize, react, vanilla-javascript
- Language: JavaScript
- Homepage:
- Size: 944 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/keydown-key/)
# keydown-key
An utility to normalize the KeyboardEvent.key especially during IME composition
## Why need this?
To address the inconsistent behavior of [IME](https://en.wikipedia.org/wiki/Input_method) across different browsers and platforms:
When selecting a [CJK character](https://en.wikipedia.org/wiki/CJK_characters) 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](https://imgur.com/63EJixc)
#### 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](https://github.com/seawind543/keydown-key):
```sh
yarn add keydown-key
```
2. Apply `keydown-key` in your application
### Example (Vanilla JS)
```javascript
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)
```javascript
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 ;
};
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 https://github.com/facebook/react/issues/13104
[4] Support IME https://github.com/seawind543/react-token-input/issues/1#issuecomment-896190656
[5] Element: keydown event https://developer.mozilla.org/en-US/docs/Web/API/Document/keydown_event#ignoring_keydown_during_ime_composition
## License
[MIT](./LICENSE)