https://github.com/kripod/keez

Frictionless hotkey handling for browsers
https://github.com/kripod/keez

event handler hotkey keyboard shortcut

Last synced: 6 months ago
JSON representation

Frictionless hotkey handling for browsers

• Host: GitHub
• URL: https://github.com/kripod/keez
• Owner: kripod
• License: mit
• Created: 2020-12-12T16:06:48.000Z (almost 5 years ago)
• Default Branch: main
• Last Pushed: 2020-12-12T16:56:58.000Z (almost 5 years ago)
• Last Synced: 2024-05-02T05:05:07.874Z (over 1 year ago)
• Topics: event, handler, hotkey, keyboard, shortcut
• Language: TypeScript
• Homepage: https://www.npmjs.com/package/keez
• Size: 23.4 KB
• Stars: 55
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-list - keez

README

          
# keez

Frictionless hotkey handling for browsers

[![npm](https://img.shields.io/npm/v/keez)](https://www.npmjs.com/package/keez)

[![npm bundle size](https://img.shields.io/bundlephobia/minzip/keez)](https://bundlephobia.com/result?p=keez)

## Usage

```js

import { captureKeys } from "keez";

const saveCommand = captureKeys("CmdOrCtrl", "S");

const italicCommand = captureKeys("CmdOrCtrl", "I");

document.addEventListener("keydown", (event) => {

  if (saveCommand(event)) {

    /* Do something, e.g. call `fetch` */

  } else if (italicCommand(event)) {

    /* Do something else, e.g. format selected text */

  }

});

```

## Features

- `CmdOrCtrl` modifier for interoperability between operating systems

- Supports synthetic events (e.g. for [React](https://reactjs.org/) elements)

- Calls `event.preventDefault()` when a match is found, suppressing handlers of the underlying browser (or even the system)

- TypeScript-based code completion for common modifier keys

- Low overhead, compared to similar libraries

## Browser support

[Every browser with the `Set` built-in](https://caniuse.com/mdn-javascript_builtins_set) is supported out of the box.

## Implementation details

There are quite a few attributes to handle keystrokes with:

|                                          | Layout-aware | Modifier-independent | Supports all events | Named non-printables |

| ---------------------------------------- | :----------: | :------------------: | :-----------------: | :------------------: |

| `key`                                    |      ✓       |          ✗           |          ✓          |        **✓**         |

| `code`                                   |      ✗       |          ✓           |          ✓          |          ✓           |

| `keyCode` / `which` _(legacy)_ |    **✓**     |        **✓**         |        **✓**        |          ✗           |

| `charCode` _(legacy)_                    |      ✓       |          ✓           |          ✗          |          ✗           |

Despite being a legacy attribute, `keyCode` is used in comparisons by default. It’s independent from modifiers, unlike the modern `key` alternative.

However, when it comes to [named key attribute values](https://www.w3.org/TR/uievents-key/#named-key-attribute-values) (e.g. `Escape` or `Backspace`), the `key` property is used under the hood.