README.md

react-keyboard-navigation-popup

This is a zero-dependency, opinionated library for providing a slack-like "jump to" popup on keyboard shortcut press.

Check out the demo here

Install

npm install --save react-keyboard-navigation-popup

Usage

Basic usage requires passing just a list of available actions.

import * as React from 'react'

import { ShortcutPopup } from "react-keyboard-navigation-popup";

class Example extends React.Component {
  render () {
    actions = [
      {
        label: "Create a reminder",
        image: "https://picsum.photos/id/1/200",
        onClick: () => console.log("Create a reminder")
      },
      ...
    ]
    return (
      <ShortcutPopup actions={actions} />
    )
  }
}

Available props

actions: MyAction[];

Required array of available actions. The ShortcutPopup component is generic and accepts a type argument for custom action types.

renderResultRow?: (result: MyAction & AddtionalResultProps) => Element;

Provide a custom component for rendering a single available action row. AddtionalResultProps provides a relevancy rating and a keyboard shortcut for selecting the option.

getSearchKeywordsForAction?: (action: MyAction) => string[];

If you want to search custom fields on the action object, provide a function that returns a list of keywords from a single action object.

onActionPress?: (action: MyAction) => void;

By default this function runs onClick from the action object, but you can also provide a custom handler based on the action fields.

getKeyShortcutForResult?: ActionKeyShortcut<MyAction>;

Override a key combination for selecting an action. ActionKeyShortcut is of type:

type ActionKeyShortcut<MyAction> = (result: {
  index: number;
  action: MyAction;
}) => { label: string; isPressed: (e: KeyboardEvent) => boolean };

Label is then returned in AddtionalResultProps as keyShortcut

getKeyShortcutForOpen?: KeyShortcut;

Override a key combination for opening the keyboard selection popup. (Cmd on mac, ctrl on other os + K by default) KeyShortcut is of type:

type KeyShortcut = () => {
  label: string;
  isPressed: (e: KeyboardEvent) => boolean;
};

getKeyShortcutForClose?: KeyShortcut;

Override a key combination for closing the keyboard selection popup. (Esc by default)

getRatingForKeywords?: (keywords: string[], searchQuery: string) => number;

Override the relevancy calculation algorithm for the set of keywords. By default it uses Damerau-Levenshtein on each pair of words from keywords, searchQuery.

showTopNResults?: number;

Show top N results from the actions list.

License

MIT © aleqsio