Narcoleptic Possum Mob

    onkey-event-manager

    1.0.0 • Public • Published

    onkey-event-manager

    npm npm bundle size (minified) npm A project badge feature text "PRs Welcome"

    🗝 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 install --save 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 with computed property names:

    <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

    Install

    npm i onkey-event-manager

    DownloadsWeekly Downloads

    8

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    7.66 kB

    Total Files

    6

    Last publish

    Collaborators

    • seanmcp