useJointState

Track joint position and velocity

Returns refs tracking a joint’s position and velocity values. Updated every physics frame without re-renders.

Signature

useJointState(name: string): {
  position: React.RefObject<number | Float64Array>;
  velocity: React.RefObject<number | Float64Array>;
}

useJointState(name: string, { kind: "scalar" }): {
  position: React.RefObject<number>;
  velocity: React.RefObject<number>;
}

useJointState(name: string, { kind: "array" }): {
  position: React.RefObject<Float64Array>;
  velocity: React.RefObject<Float64Array>;
}

Usage

import { useJointState } from "mujoco-react";

function JointDisplay() {
  const { position } = useJointState("joint1", { kind: "scalar" });
  const textRef = useRef<{ text: string } | null>(null);

  useFrame(() => {
    const angle = position.current;
    if (textRef.current) {
      textRef.current.text = `${(angle * 180 / Math.PI).toFixed(1)}°`;
    }
  });

  return <Text ref={textRef} position={[0, 0.3, 0]} />;
}

Return Value

Field	Type	Description
position	RefObject<number | Float64Array>	Joint position(s) from data.qpos. Scalar for hinge/slide, Float64Array for ball/free.
velocity	RefObject<number | Float64Array>	Joint velocity/velocities from data.qvel. Scalar for hinge/slide, Float64Array for ball/free.

Pass { kind: "scalar" } for hinge/slide joints when you want numeric refs. Pass { kind: "array" } for ball/free joints when you want typed-array refs. Omit kind for generic code that handles both shapes.

Array Size by Joint Type

Joint Type	Position Size	Velocity Size
hinge	1 (scalar)	1 (scalar)
slide	1 (scalar)	1 (scalar)
ball	4 (quaternion)	3 (angular vel)
free	7 (pos + quat)	6 (lin vel + ang vel)

Notes

• Returns refs for zero-overhead per-frame reads
• For hinge/slide joints, values are scalars (not arrays)
• For ball/free joints, typed arrays are preallocated once and reused via .set() each physics frame — no per-frame allocation
• For free joints, position is [x, y, z, qw, qx, qy, qz]