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

# IkGizmo

> Interactive IK target with PivotControls

A draggable 3D gizmo (powered by drei's PivotControls) that drives inverse kinematics. Drag the gizmo to move the robot's end-effector. Requires a `controller` from `useIkController()`.

## Usage

```tsx theme={null}
import { IkGizmo, ModelSites, useIkController } from "mujoco-react";

function MyScene() {
  const ik = useIkController({ siteName: ModelSites.franka.tcp });

  return ik ? <IkGizmo controller={ik} /> : null;
}
```

### Custom Site

Override the site tracked by this gizmo (defaults to the controller's `siteName`):

```tsx theme={null}
<IkGizmo controller={ik} siteName="left_hand" scale={0.25} />
```

### Custom Drag Handler

```tsx theme={null}
<IkGizmo
  controller={ik}
  onDrag={({ position, quaternion }) => {
    // Consumer handles the response — IK is NOT auto-enabled
    console.log("Target:", position, quaternion);
  }}
/>
```

## Props

<ParamField body="controller" type="IkContextValue" required>
  The IK controller value returned by `useIkController()`.
</ParamField>

<ParamField body="siteName" type="string" default="controller's siteName">
  MuJoCo site to track. Defaults to the `useIkController` config's site.
</ParamField>

<ParamField body="scale" type="number" default="0.18">
  Visual scale of the gizmo handles.
</ParamField>

<ParamField body="onDrag" type="({ position, quaternion }) => void">
  Custom drag callback. When provided, the gizmo does **not** automatically enable IK — the consumer is responsible for handling the drag.
</ParamField>

## Behavior

**When not dragging:**

* The gizmo tracks the MuJoCo site's world position and orientation each frame
* It "follows" the end-effector as the robot moves

**When dragging (no `onDrag` prop):**

* IK is automatically enabled via `controller.setIkEnabled(true)`
* The gizmo's position/orientation is written to the IK target
* The IK solver runs each frame to compute joint angles
* OrbitControls are disabled during drag

**When dragging (with `onDrag` prop):**

* The `onDrag` callback fires with `{ position, quaternion }`
* IK is NOT automatically enabled — the consumer decides what to do
* OrbitControls are disabled during drag

## Programmatic Control

Use the controller value from `useIkController()`:

```tsx theme={null}
const ik = useIkController({ siteName: ModelSites.franka.tcp });

// Animate the gizmo to a position over 500ms
ik?.moveTarget(new THREE.Vector3(0.5, 0, 0.3), 500);

// Snap the gizmo to current site position
ik?.syncTargetToSite();

// Enable/disable IK solving
ik?.setIkEnabled(true);
```

## Notes

* Requires a `controller` prop from `useIkController()`
* The IK solver uses the controller's inferred or explicit joint/actuator selection
* Disable IK with `controller.setIkEnabled(false)` when using custom control (e.g., `useBeforePhysicsStep`)