keyheld

Tracks whether a specific key is being held down. Emits only when the held state changes.

Terminal window
npm install --save cereb

Basic Usage

import { keyheld } from "cereb";


keyheld(window, { code: "Space" }).on((signal) => {
  if (signal.value.held) {
    console.log("Space is held down");
  } else {
    console.log("Space was released");
  }
});

Signature

function keyheld(target: EventTarget, options: KeyheldOptions): Stream<KeyheldSignal>

Options

OptionTypeDescription
codeKeyCodePhysical key code to track (required)

Signal Value

PropertyTypeDescription
heldbooleanWhether the key is currently held

Examples

Toggle Mode While Key Held

import { keyheld } from "cereb";


const shiftHeld$ = keyheld(window, { code: "ShiftLeft" });


shiftHeld$.on((signal) => {
  canvas.style.cursor = signal.value.held ? "crosshair" : "default";
});

Zoom Mode with when Operator

import { wheel, keyheld } from "cereb";
import { when, extend } from "cereb/operators";


// Create zoom mode signal (requires `opened` property for `when`)
const zoomMode$ = keyheld(window, { code: "KeyZ" })
  .pipe(extend((signal) => ({ opened: signal.value.held })));


// Only handle wheel events when Z is held
wheel(element)
  .pipe(when(zoomMode$))
  .on((signal) => {
    const delta = signal.value.deltaY;
    setScale(scale * Math.exp(-delta * 0.005));
  });

Sprint While Holding Shift

const sprintMode$ = keyheld(window, { code: "ShiftLeft" });


sprintMode$.on((signal) => {
  player.speed = signal.value.held ? 10 : 5;
});