API & Reference

Sections

• Decorators
• @keydown
• @keydownScoped
• Keys

Decorators

@keydown

Scope	Arguments	Description
Class	(Optional) integer key codes or strings, or an array of the same. (See below for key reference.)	Class decorator to pass keydown events into the decorated component. · Alias: keydown( MyComponent )
Method	(Required) integer key codes or strings, or an array of the same.	Method decorator that assigns keys to the decorated method and establishes the component DOM as the scope where that keybinding should work. It passes the keydown event into the method, and calls it with the component instance as context. Compare to @keydownScoped. · Alias: setBinding( { target, fn, keys } )

Examples

// class decorator with string arguments

@keydown( 'up', 'down', 'right', 'left' )
class MyComponent extends React.Component {}


// class decorator with array of key codes

@keydown( [ 37, 38, 39, 40 ] )
class MyComponent extends React.Component {}


// higher-order component pattern with no key arguments

class MyComponent extends React.Component {}
export default keydown( MyComponent );


// higher-order component with key arguments

class MyComponent extends React.Component {}
export default keydown( 'up', 'down' )( MyComponent );


// method decorator

class MyComponent extends React.Component {

  @keydown( 'ctrl+enter' )
  submit( event ) {}
}


// non-decorator pattern

import { onMount, onUnmount, setBinding } from 'react-keydown/dist/event_handlers';

class MyComponent extends React.Component {
  componentDidMount() {
    onMount( this );
  }
  componentWillUnmount() {
    onUnmount( this );
  }
  submit( event ) {}
}

setBinding({
  target: MyComponent.prototype,
  fn: MyComponent.prototype.submit,
  keys: ['ctrl+enter']
});

@keydownScoped

Scope	Arguments	Description
Method	Same as @keydown method decorator	When used with the class decorator (required), this bypasses the need to examine props manually. It will look for the supplied key arguments in the incoming props and, if found, trigger the decorated method. Unlike @keydown, it does not establish the component of the decorated method as the scope where the binding will work. It relies instead on the class decorator to establish the scope. Alias: None - work with nextProps.keydown.event prop in React lifecycle methods.

Example

@keydown( ['ctrl+shift+j', 'ctrl+shift+k'] )
class MyComponent extends React.Component {
  render() {
    return <MyOtherComponent {...this.props} />
  }
}

// this keybinding will work in the larger scope of the parent component
class MyOtherComponent extends React.Component {
  @keydownScoped( 'ctrl+shift+j' )
  goDown( event ) {}
}

Keys

React Keydown can currently handle the following strings as key specifications:

• a-z
• 0-9
• ; - = \ / , . \ ` [ ]
• enter (aka return), tab, up, down, left, right, space, backspace

Note that you can use shift + the above keys to specify the shifted version of that key – i.e. 'shift+1' to specify the '!' key. Case is otherwise ignored.

Modifier Keys

You can also prepend any number of the following modifier keys to your key specification, separating keys with +:

• ctrl (aka control)
• shift
• alt (aka option)
• meta (aka command or cmd)

Examples

@keydown( 'j', 'k', 'h', 'l' )
@keydown( 'ctrl+shift+enter', 'cmd + z' )

Many more keys, including key sequences, as well as friendlier syntax, will arrive with future versions.