Keyboard

A minimalistic keyboard API. You can use it move the main sprite or respond to a key press.

let { initKeys, keyPressed } = kontra;

// this function must be called first before keyboard
// functions will work
initKeys();

function update() {
  if (keyPressed('left')) {
    // move left
  }
}
import { initKeys, keyPressed } from 'path/to/kontra.mjs';

// this function must be called first before keyboard
// functions will work
initKeys();

function update() {
  if (keyPressed('left')) {
    // move left
  }
}
import { initKeys, keyPressed } from 'kontra';

// this function must be called first before keyboard
// functions will work
initKeys();

function update() {
  if (keyPressed('left')) {
    // move left
  }
}

Table of Contents

Available Keys

Below is a list of keys that are provided by default. If you need to extend this list, you can use the keyMap property.

  • a-z
  • 0-9
  • enter, esc, space, left, up, right, down

bindKeys(​keys, callback[, options])

Bind a set of keys that will call the callback function when they are pressed. Takes a single key or an array of keys. Is passed the original KeyboardEvent as a parameter.

By default, the default action will be prevented for any bound key. To not do this, pass the preventDefault option.

let { initKeys, bindKeys } = kontra;

initKeys();

bindKeys('p', function(e) {
  // pause the game
}, 'keyup');
bindKeys(['enter', 'space'], function(e) {
  // fire gun
});
import { initKeys, bindKeys } from 'path/to/kontra.mjs';

initKeys();

bindKeys('p', function(e) {
  // pause the game
}, 'keyup');
bindKeys(['enter', 'space'], function(e) {
  // fire gun
});
import { initKeys, bindKeys } from 'kontra';

initKeys();

bindKeys('p', function(e) {
  // pause the game
}, 'keyup');
bindKeys(['enter', 'space'], function(e) {
  // fire gun
});

bindKeys Parameters

keys

String or an Array of Strings. Key or keys to bind.

callback

Function. The function to be called when the key is pressed.

options Optional

Object. Bind options.

options.handler Optional

'keydown' or 'keyup'. Whether to bind to keydown or keyup events. Defaults to keydown.

options.preventDefault Optional

Boolean. Call event. preventDefault() when the key is activated. Defaults to true.

initKeys(​)

Initialize keyboard event listeners. This function must be called before using other keyboard functions.

keyMap

Object. A map of KeyboardEvent code values to key names. Add to this object to expand the list of available keys.

let { keyMap, bindKeys } = kontra;

keyMap['ControlRight'] = 'ctrl';

bindKeys('ctrl', function(e) {
  // handle ctrl key
});
import { keyMap, bindKeys } from 'path/to/kontra.mjs';

keyMap['ControlRight'] = 'ctrl';

bindKeys('ctrl', function(e) {
  // handle ctrl key
});
import { keyMap, bindKeys } from 'kontra';

keyMap['ControlRight'] = 'ctrl';

bindKeys('ctrl', function(e) {
  // handle ctrl key
});

keyPressed(​key)

Check if a key is currently pressed. Use during an update() function to perform actions each frame.

let { Sprite, initKeys, keyPressed } = kontra;

initKeys();

let sprite = Sprite({
  update: function() {
    if (keyPressed('left')){
      // left arrow pressed
    }
    else if (keyPressed('right')) {
      // right arrow pressed
    }

    if (keyPressed('up')) {
      // up arrow pressed
    }
    else if (keyPressed('down')) {
      // down arrow pressed
    }
  }
});
import { Sprite, initKeys, keyPressed } from 'path/to/kontra.mjs';

initKeys();

let sprite = Sprite({
  update: function() {
    if (keyPressed('left')){
      // left arrow pressed
    }
    else if (keyPressed('right')) {
      // right arrow pressed
    }

    if (keyPressed('up')) {
      // up arrow pressed
    }
    else if (keyPressed('down')) {
      // down arrow pressed
    }
  }
});
import { Sprite, initKeys, keyPressed } from 'kontra';

initKeys();

let sprite = Sprite({
  update: function() {
    if (keyPressed('left')){
      // left arrow pressed
    }
    else if (keyPressed('right')) {
      // right arrow pressed
    }

    if (keyPressed('up')) {
      // up arrow pressed
    }
    else if (keyPressed('down')) {
      // down arrow pressed
    }
  }
});

keyPressed Parameters

key

String. Key to check for pressed state.

keyPressed Return value

Boolean. true if the key is pressed, false otherwise.

unbindKeys(​keys[, options])

Remove the callback function for a bound set of keys. Takes a single key or an array of keys.

let { unbindKeys } = kontra;

unbindKeys('left');
unbindKeys(['enter', 'space']);
import { unbindKeys } from 'path/to/kontra.mjs';

unbindKeys('left');
unbindKeys(['enter', 'space']);
import { unbindKeys } from 'kontra';

unbindKeys('left');
unbindKeys(['enter', 'space']);

unbindKeys Parameters

keys

String or an Array of Strings. Key or keys to unbind.

options Optional

Object. Unbind options.

options.handler Optional

'keydown' or 'keyup'. Whether to unbind from keydown or keyup events. Defaults to keydown.