> ## Documentation Index
> Fetch the complete documentation index at: https://dadd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# useJointState

> Track joint position and velocity

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

## Signature

```tsx theme={null}
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

```tsx theme={null}
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]`