useKeyboardTeleop

Map keyboard keys to actuator controls

Map keyboard keys to actuator controls for teleoperation. Supports delta (hold), toggle (press), and set (hold) modes.

Signature

useKeyboardTeleop(config: {
  bindings: Record<string, KeyBinding>;
  enabled?: boolean;
}): void

Usage

import { ModelActuators, useKeyboardTeleop } from "mujoco-react";

function TeleopControls() {
  useKeyboardTeleop({
    bindings: {
      "w": { actuator: ModelActuators.franka.actuator1, delta: 0.1 },
      "s": { actuator: ModelActuators.franka.actuator1, delta: -0.1 },
      "a": { actuator: ModelActuators.franka.actuator2, delta: 0.1 },
      "d": { actuator: ModelActuators.franka.actuator2, delta: -0.1 },
      "space": { actuator: ModelActuators.franka.gripper, toggle: [0, 0.04] },
    },
    enabled: true,
  });

  return null;
}

Binding Modes

delta — Increment while held

Add a delta value to the actuator each frame while the key is held:

"w": { actuator: "forward", delta: 0.1 }
// While "w" is held: ctrl[forward] += 0.1 per frame

toggle — Toggle between two values on press

Press once to set the first value, press again for the second:

import { ModelActuators } from "mujoco-react";

"space": { actuator: ModelActuators.franka.gripper, toggle: [0, 0.04] }
// Press space: ctrl[ModelActuators.franka.gripper] = 0
// Press again: ctrl[ModelActuators.franka.gripper] = 0.04

set — Set value while held

Set a fixed value while the key is held, revert when released:

"x": { actuator: "brake", set: 1.0 }
// While 'x' is held: ctrl[brake] = 1.0
// On release: ctrl[brake] = previous value

Config

Field	Type	Default	Description
bindings	Record<string, KeyBinding>	required	Key → actuator mapping
enabled	boolean	true	Enable/disable all bindings

KeyBinding

interface KeyBinding {
  actuator: string;           // Actuator name
  delta?: number;             // Increment per frame while held
  toggle?: [number, number];  // Two values to alternate on press
  set?: number;               // Value while held
}

Notes

• Key names use KeyboardEvent.key (lowercase for letters, ' ' for space, etc.)
• Multiple keys can target the same actuator
• Disabled when enabled: false — useful for modal UIs