> ## 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.

# useSensor

> Read sensor values by name

Read a MuJoCo sensor's value by name. Returns a handle with `read()` updated every physics frame.

## Signature

```tsx theme={null}
useSensor(name: Sensors): SensorHandle
```

## Usage

```tsx theme={null}
import { ModelSensors, useSensor } from "mujoco-react";

function ImuDisplay() {
  const angularVelocity = useSensor(
    ModelSensors.g1["imu-torso-angular-velocity"]
  );
  const textRef = useRef<{ text: string } | null>(null);

  useFrame(() => {
    const v = angularVelocity.read();
    const speed = Math.sqrt(v[0] ** 2 + v[1] ** 2 + v[2] ** 2);
    if (textRef.current) textRef.current.text = `${speed.toFixed(2)} rad/s`;
  });

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

## Return Value

```tsx theme={null}
interface SensorHandle {
  read(): Float64Array;
  dim: number;
  name: Sensors;
}
```

| Field    | Type                 | Description                                                   |
| -------- | -------------------- | ------------------------------------------------------------- |
| `read()` | `() => Float64Array` | Current sensor reading from `data.sensordata`                 |
| `dim`    | `number`             | Number of values (e.g., 3 for a force sensor, 1 for a scalar) |
| `name`   | `Sensors`            | Sensor name                                                   |

## Sensor Types

Common MuJoCo sensor types and their dimensions:

| Sensor Type     | `dim` | Description          |
| --------------- | ----- | -------------------- |
| `touch`         | 1     | Contact normal force |
| `accelerometer` | 3     | Linear acceleration  |
| `gyro`          | 3     | Angular velocity     |
| `force`         | 3     | Constraint force     |
| `torque`        | 3     | Constraint torque    |
| `jointpos`      | 1     | Joint position       |
| `jointvel`      | 1     | Joint velocity       |
| `framepos`      | 3     | Frame position       |
| `framequat`     | 4     | Frame orientation    |

## Notes

* The `read()` array is updated every frame via `useAfterPhysicsStep`
* If the sensor doesn't exist, `read()` returns an empty `Float64Array`
* For enumerating all sensors, use `api.getSensors()`
* The `name` parameter accepts `string` by default, or a generated union type if you use [`mujocoReact()`](/guides/type-safe-names)