README.md

🎹 Keyboardist: Declarative keyboard listener

A declarative way to add keyboard shortcuts to your browser applications. Here is a simple demo

For using with React, there's React Keyboardist.

Example:

import { createListener } from "keyboardist";

// by default it listens to keydown
const listener = createListener();

listener.subscribe("Down", () => {
  console.log("Pressed down");
});

listener.subscribe("Shift+Down", () => {
  console.log("Pressed Shift + down");
});

Install

Example:

npm install keyboardist

Usage

The Keyboardist constructor returns a listener object that has only one method: subscribe.

subscribe accepts two arguments: a key or key combination and a method that will be called when that key (or key combination) is triggered by the user.

Example:

import { createListener } from "keyboardist";

const listener = new createListener();

const keySubscription = listener.subscribe("Slash", () => {
  focusSearch();
});

The object returned by subscribe has an unsubscribe method.

// create a subscription
const keySubscription = listener.subscribe("Slash", () => {
  focusSearch();
});

// remove the subscription
keySubscription.unsubscribe();

Multiple listeners for a Key

You can add multiple listeners for the same key, and they will be executed starting from the last one.

// create a subscription

listener.subscribe("Space", () => {
  console.log("A");
});

listener.subscribe("Space", () => {
  console.log("B");
});

listener.subscribe("Space", () => {
  console.log("C");
});

// the console will log 'C', then 'B', then 'A' when the spacebr is pressed.

Key Monitor

Keyboardist's event listener has a setMonitor method that let's you set a function that will monitor all key events. You can either pass true to use the default built-in monitor or pass a function.

Default monitor is useful in development when you don't know the correct key name you want to use.

const listener = new Keyboardist();
// ue the default monitor
listener.setMonitor(true);

// will show the key names / combination as you type them. For example:
// `:keyboard event: KeyA`
// `:keyboard event: Slash`
// `:keyboard event: Shift+Space`

You can also pass a custom function that accepts three parameters: keyName, matched which is true if there's at least a listener for that key, and the originalEvent (which has already been preventDefaulted at this point).

const listener = new Keyboardist();
// ue the default monitor
listener.setMonitor((keyName, matched, originalEvent) => {
  document.getElementById("monitor").innerHTML = `You pressed ${keyName}`;
});

Other events

By default, the listener listens to keydown events, but you can pass keyup as an argument to Keyboardist to use that event instead

const downListener = createListener();
const upListener = Keyboardist("keyup");

downListener.subscribe("a", () => {
  console.log("Just pressed the A key");
});

upListener.subscribe("a", () => {
  console.log("Just released the A key");
});

Stop listening

Internally createListener attaches only one event listener to your document to listen to your keystrokes. If you ever want to remove that listener you can call stopListening on the listener instance.

const listener = createListener();

listener.subscribe("a", () => {
  console.log("Just pressed the A key");
});

// Remove the event listener from the document
listener.stopListening();

// Reattach it again:
listener.startListening();