Keycombo-parse NPM

keycombo-parse

Introduction

When alt key is involved in to key combination, the value of e.key becomes strange. For example, hitting ⌥ + A, you'll get å as e.key value. The e.code value is more accurate in this case: KeyA, but a bit lengthy.

While registering a keyboard shorcut event, devolopers want something like this:

import kc from "keycombo-parse"

document.addEventListener("keydown", e => {
	if (kc("⇧ ⌥ ⌘ + C", e)) {
		// shortcut activated
	}
})

The key combination string: ⇧ ⌥ ⌘ + C, is quite succinct, but might be hard to type for those not using a text expander such as espanso. In this package we also support key combo string in plain text: shift alt meta + C.

How to use

After installation with pnpm add keycombo-parse, you could import it to browser client-side JavaScript code:

// using the default export
import isKeyComboMatch from "keycombo-parse"

document.addEventListener("keydown", e => {
	if (isKeyComboMatch("⇧ ⌥ ⌘ + H", e)) {
		showHelp()
	}
})

const showHelp() => console.log("Displaying help dialog...")

or get the standardized keycombo string:

import { standardKeyCombo } from "keycombo-parse"

standardKeyCombo(" cmd shift option + k") // log output: ⇧ ⌥ ⌘ + K

if you want have a shortcut that requires hitting content key twice, define it this way:

import isKeyComboMatch from "keycombo-parse"

document.addEventListener("keydown", e => {
	if (isKeyComboMatch("⌘ + C", e)) {
		copyName()
	} else if (isKeyComboMatch("⌘ + CC", e)) {
		copySVG()
	}
})

const copyName = () => console.log("Copying icon name...")
const copySVG = () => console.log("Copying icon SVG...")

Restriction

A few things to note:

We use space as separator, so spaces are necessary
We recognize alt, option, or ⌥, all supported!
We avoid differentiating modifier keys on the right side, so ShiftLeft and ShiftRight are treated as the same
Case-insensitive, so Alt and alt are both acceptable
It's recommended that key combination always end with a non-modifier key, for example: ⌘ + C, ⌘ + 1, or ⌘ + [
A single non-modifer key are supported only when user not typing into a text field
A single modifer key: shift, alt, meta, ctrl are also supported
Function keys are not supported

Idea behind this package

npm.io

`e.code` and its alternatives

When naming the key combo string, you can use the complete key code name, for example: Shift Meta + KeyC, or the more concise couterpart: ⇧ ⌘ + C.