onkey-event-manager

🗝 Easily map onKey functions to keyboard events

Basics

onkey-event-manager simplifies the process of listening for and acting on key changes.

import onKey from 'onkey-event-manager'

const OpenButton = ({ open }) => (
  <button onKeyDown={onKey({ ArrowDown: open })}>Open</button>
)

Install

Add onkey-event-manager to your project:

npm i onkey-event-manager
# or
yarn add onkey-event-manager

Use

Import the default onKey function from onkey-event-manager and add it to your code:

...
import onKey from 'onkey-event-manager'

function Button({ onClick }) {
    return (
        <button
            onClick={onClick}
            onKeyDown={onKey({ ArrowDown: onClick })}
        >
            <code>onClick</code> will fire when I am clicked
            or when I'm focused and you press the down arrow.
        </button>
    )
}

Why?

JavaScript provides three keyboard events to trigger actions: keydown, keyup, and keypress. In order to listen to specific keys, you need to pass a function that takes an event and compares the event.key to the desired key like so:

Traditional React example

function Accordion(props) {
  const [isOpen, setIsOpen] = React.useState(false)

  function open() {
    setIsOpen(true)
  }

  function openOnArrowDown(event) {
    if (event.key === 'ArrowDown') {
      open()
    }
  }

  return (
    <div>
      <h2>{props.title}</h2>
      <button
        aria-label={'Toggle accordion'}
        onClick={open}
        onKeyDown={openOnArrowDown}
      >
        ▾
      </button>
      {isOpen && <div>{props.children}</div>}
    </div>
  )
}

This is fine but becomes cumbersome when trying to make complex user interfaces accessible with multiple keyboard interactions.

onkey-event-manager abstracts the event key filtering logic, simplifying the process of listening for keys.

API

Version 1+ of onkey-event-manager comprises a single default export: onKey.

onKey()

onKey is a simple function that listens for an event, compares it to a set of selected keys, then calls the action and passes the event object if there is a match.

onKey(Object<String, Function>)

If there is a single key you want to listen for, pass an object inline:

<button onKeyDown={onKey({ ArrowDown: openMenu })} >

For more complex listening, consider calling the function outside of the return to keep your JSX clean:

function SelectOption(props) {
  const handleKeyDown = onKey({
    ArrowUp: props.decrementIndex,
    ArrowDown: props.incrementIndex
  })
  return <li onKeyDown={handleKeyDown}>{props.children}</li>
}

Author

Sean McPherson

License

MIT