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

# useCtrl

> Read/write a single actuator control by name

Provides handle-based read/write access to a single actuator's control value by name.

## Signature

```tsx theme={null}
useCtrl(name: Actuators): CtrlHandle
```

## Usage

```tsx theme={null}
import { ModelActuators, useCtrl } from "mujoco-react";

function GripperControl() {
  const gripper = useCtrl(ModelActuators.franka.gripper);

  return (
    <div>
      <button onClick={() => gripper.write(0.04)}>Open</button>
      <button onClick={() => gripper.write(0.0)}>Close</button>
    </div>
  );
}
```

### Reading in useFrame

```tsx theme={null}
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 <Text ref={textRef} position={[0, 0.5, 0]} />;
}
```

### Inside useBeforePhysicsStep

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