Skip navigation

Keyboard

A simple 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('arrowleft')) {
    // 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('arrowleft')) {
    // move left
  }
}

import { initKeys, keyPressed } from 'kontra';

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

function update() {
  if (keyPressed('arrowleft')) {
    // 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, arrowleft, arrowup, arrowright, arrowdown

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, onKey } = kontra;

keyMap['ControlRight'] = 'ctrl';

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

import { keyMap, onKey } from 'path/to/kontra.mjs';

keyMap['ControlRight'] = 'ctrl';

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

import { keyMap, onKey } from 'kontra';

keyMap['ControlRight'] = 'ctrl';

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

keyPressed(​keys)

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('arrowleft')){
      // left arrow pressed
    }
    else if (keyPressed('arrowright')) {
      // right arrow pressed
    }

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

import { Sprite, initKeys, keyPressed } from 'path/to/kontra.mjs';

initKeys();

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

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

import { Sprite, initKeys, keyPressed } from 'kontra';

initKeys();

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

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

Parameters

keys

String or an Array of Strings. Key or keys to check for pressed state.

Return value

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

offKey(​keys[, options])

Unregister the callback function for a key. Takes a single key or an array of keys.

let { offKey } = kontra;

offKey('arrowleft');
offKey(['enter', 'space']);

import { offKey } from 'path/to/kontra.mjs';

offKey('arrowleft');
offKey(['enter', 'space']);

import { offKey } from 'kontra';

offKey('arrowleft');
offKey(['enter', 'space']);

Parameters

keys

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

options Optional

Object. Unregister options.

options.handler Optional

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

onKey(​keys, callback[, options])

Register a function to be called when a key is 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, onKey } = kontra;

initKeys();

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

import { initKeys, onKey } from 'path/to/kontra.mjs';

initKeys();

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

import { initKeys, onKey } from 'kontra';

initKeys();

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

Parameters

keys

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

callback

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

options Optional

Object. Register options.

options.handler Optional

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

options.preventDefault Optional

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