react-use-hotkeys

React hook for creating simple keyboard shortcuts.

Installation

npm install @reecelucas/react-use-hotkeys

Example Usage

import useHotkeys from "@reecelucas/react-use-hotkeys";

All hotkey combinations must use valid KeyBoardEvent "key" values. A full list can be found on MDN and Wes Bos has created a great interactive lookup.

// Single keys
useHotkeys("Escape", () => {
  console.log("Some action");
});

useHotkeys("F7", () => {
  console.log("Some action");
});

// Modifier combinations
useHotkeys("Meta+Shift+z", () => {
  console.log("Some action");
});

// Key sequences
useHotkeys("w s d", () => {
  console.log("Some action");
});

useHotkeys('w " " d', () => {
  // space key in sequence (`w ' ' d` also works)
  console.log("Some action");
});

// Multiple key combinations mapped to the same callback
useHotkeys(["Control+z", "Meta+z"], () => {
  console.log("Some action");
});

useHotkeys(["a", "Meta+z", "w s d"], () => {
  console.log("Some action");
});

The following patterns are not supported:

// Modifier keys in sequences
useHotkeys("Control i d", () => {
  console.log("I won't run!");
});

// Modifier combinations in sequences
useHotkeys("Control+z i d", () => {
  console.log("I won't run!");
});

If you find a use case where the API is too restrictive you can use the escape hatch to perform whatever custom logic you need:

useHotkeys("*", (event) => {
  console.log("I will run on every keydown event");

  if (customKeyLogic(event)) {
    console.log("some action");
  }
});

Options

enabled

You can disable the hook by passing enabled: false. When disabled the hook will stop listening for keydown events:

useHotkeys(
  "Escape",
  () => {
    console.log("I won't run!");
  },
  { enabled: false }
);

enableOnContentEditable

By default, the hook will ignore keydown events originating from elements with the contenteditable attribute, since this behaviour is normally what you want. If you want to override this behaviour you can pass enableOnContentEditable: true:

useHotkeys(
  "Escape",
  () => {
    console.log("Some action");
  },
  { enableOnContentEditable: true }
);

ignoredElementWhitelist

By default, the hook will ignore keydown events originating from INPUT and TEXTAREA elements, since this behaviour is normally what you want. If you want to override this behaviour you can use ignoredElementWhitelist:

useHotkeys(
  "Escape",
  () => {
    console.log("I will now run on input elements");
  },
  { ignoredElementWhitelist: ["INPUT"] }
);

useHotkeys(
  "Escape",
  () => {
    console.log("I will now run on input and textarea elements");
  },
  { ignoredElementWhitelist: ["INPUT", "TEXTAREA"] }
);

eventListenerOptions

You can pass AddEventListenerOptions if you need to listen for keydown events in the capturing phase:

useHotkeys(
  "Escape",
  () => {
    console.log("I will run in the capturing phase");
  },
  {
    eventListenerOptions: {
      capture: true,
    },
  }
);

Call Signature

useHotkeys(
  hotkeys: string | string[],
  callback: (event: KeyboardEvent) => void,
  options?: {
    enabled?: boolean;
    enableOnContentEditable?: boolean;
    ignoredElementWhitelist?: ("INPUT" | "TEXTAREA")[];
    eventListenerOptions?: AddEventListenerOptions;
  }
) => void;

Tests

Tests use Jest and react-testing-library.

git clone [email protected]:reecelucas/react-use-hotkeys.git
cd react-use-hotkeys
yarn
yarn test

LICENSE

MIT