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