---
title: "useCtrl"
description: "Read/write a single actuator control by name"
icon: "sliders"
---
Provides handle-based read/write access to a single actuator's control value by name.
## Signature
```tsx
useCtrl(name: Actuators): CtrlHandle
```
## Usage
```tsx
import { ModelActuators, useCtrl } from "mujoco-react";
function GripperControl() {
const gripper = useCtrl(ModelActuators.franka.gripper);
return (
);
}
```
### Reading in useFrame
```tsx
function GripperDisplay() {
const gripper = useCtrl(ModelActuators.franka.gripper);
const textRef = useRef<{ text: string } | null>(null);
useFrame(() => {
if (textRef.current) {
textRef.current.text = `Gripper: ${gripper.read().toFixed(3)}`;
}
});
return ;
}
```
### Inside useBeforePhysicsStep
```tsx
import { ModelActuators, useBeforePhysicsStep, useCtrl } from "mujoco-react";
function MyController() {
const shoulder = useCtrl(ModelActuators.franka.actuator1);
const elbow = useCtrl(ModelActuators.franka.actuator2);
useBeforePhysicsStep(({ data }) => {
shoulder.write(Math.sin(data.time));
elbow.write(Math.cos(data.time) * 0.5);
});
return null;
}
```
## Return Value
```tsx
interface CtrlHandle {
read(): number;
write(value: number): void;
name: Actuators;
range: [number, number];
}
```
| Field | Type | Description |
|-------|------|-------------|
| `read()` | `() => number` | Read the current control value from `data.ctrl` |
| `write()` | `(v: number) => void` | Write a control value directly to `data.ctrl` |
| `name` | `Actuators` | Actuator name |
| `range` | `[number, number]` | Control range `[min, max]` from `actuator_ctrlrange` |
## Notes
- `read()` and `write()` operate directly on `data.ctrl` — no re-renders
- For setting multiple actuators at once, use `api.setCtrl({ name: value, ... })`
- The actuator index is resolved once on mount
- The `name` parameter accepts `string` by default, or a generated union type if you use [`mujocoReact()`](/guides/type-safe-names)
Actuator IDs identify metadata; control addresses index `data.ctrl`. New actuator
metadata includes `ctrlAdr`, `ctrlCount`, and `ranges`. A PID or orientation
actuator can own multiple inputs. Write a complete vector with
`api.setCtrl(name, values)` or access one input with `useCtrl(name, inputIndex)`.
Calling scalar-only controls on a multi-input actuator without an input selector
throws an actionable error.