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

# Introduction

> Composable React Three Fiber wrapper around MuJoCo WASM

# mujoco-react

**mujoco-react** is a composable [React Three Fiber](https://r3f.docs.pmnd.rs/) wrapper around the official [@mujoco/mujoco](https://www.npmjs.com/package/@mujoco/mujoco) WASM bindings. It provides components for loading models, stepping physics, and rendering bodies. Controllers like IK are opt-in plugins.

<CardGroup cols={2}>
  <Card title="Composable" icon="puzzle-piece">
    `<IkGizmo />`, `<Debug />`, `<ContactMarkers />` etc. are R3F children you add to your scene.
  </Card>

  <Card title="Controller Pattern" icon="scale-balanced">
    Controllers are React components that call `useBeforePhysicsStep`. Write your own or use the built-in ones.
  </Card>

  <Card title="Pluggable IK" icon="plug">
    Swap in any IK solver via `ikSolveFn`, or skip `useIkController` entirely and solve IK yourself in `useBeforePhysicsStep`.
  </Card>

  <Card title="Full MuJoCo" icon="atom">
    Contacts, sensors, tendons, flex bodies, raycasting, domain randomization. The full MuJoCo API via React hooks.
  </Card>
</CardGroup>

## Quick Start

```bash theme={null}
npm install mujoco-react @react-three/fiber @react-three/drei three
```

```tsx theme={null}
import {
  MujocoProvider, MujocoCanvas, ModelSites, useIkController, IkGizmo,
} from "mujoco-react";
import { OrbitControls } from "@react-three/drei";

function Scene() {
  const ik = useIkController({ siteName: ModelSites.franka.tcp });
  return (
    <>
      <OrbitControls makeDefault />
      {ik && <IkGizmo controller={ik} />}
      <ambientLight intensity={0.7} />
      <directionalLight position={[1, 2, 5]} castShadow />
    </>
  );
}

function App() {
  return (
    <MujocoProvider>
      <MujocoCanvas
        config={{
          src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
          sceneFile: "scene.xml",
          homeJoints: [1.707, -1.754, 0.003, -2.702, 0.003, 0.951, 2.490],
        }}
        camera={{ position: [2, -1.5, 2.5], up: [0, 0, 1], fov: 45 }}
        shadows
        style={{ width: "100%", height: "100vh" }}
      >
        <Scene />
      </MujocoCanvas>
    </MujocoProvider>
  );
}
```

This loads the Franka Panda from [DeepMind Menagerie](https://github.com/google-deepmind/mujoco_menagerie), renders all bodies, and adds an interactive IK gizmo on the end-effector.

## Controllers

A controller is a React component that calls `useBeforePhysicsStep` to write `data.ctrl` each frame:

```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;
}
```

Add it as a child of `<MujocoCanvas>`:

```tsx theme={null}
<MujocoCanvas config={config}>
  <MyController />
</MujocoCanvas>
```

IK, teleoperation, RL policies, state machines all follow this pattern. The `useIkController()` hook follows this same pattern. You can also [plug in your own IK solver](/hooks/use-ik-controller#with-custom-solver) or skip it entirely.

<Tip>
  See the [Building Controllers](/guides/building-controllers) guide for config-driven patterns, `createController` factory, IK gizmo coexistence, and multi-arm support.
</Tip>

## Design Philosophy

mujoco-react follows the same pattern as [react-three-rapier](https://github.com/pmndrs/react-three-rapier):

* **Library handles MuJoCo engine concerns only**: WASM lifecycle, physics stepping, body rendering
* **Controllers are opt-in plugins**: IK, teleoperation, custom controllers are composable components
* **Consumers compose everything else**: lights, grid, camera controls, UI, game logic
* **All scene elements are R3F children**: no config objects for visual-only things

`<MujocoCanvas>` wraps R3F `<Canvas>` and forwards all Canvas props. For full control over the Canvas (gl settings, post-processing, etc.), use `<MujocoPhysics>` inside your own:

<Tabs>
  <Tab title="MujocoCanvas">
    ```tsx theme={null}
    <MujocoCanvas config={config} shadows camera={...}>
      <Scene />
      <OrbitControls />
    </MujocoCanvas>
    ```
  </Tab>

  <Tab title="MujocoPhysics">
    ```tsx theme={null}
    <Canvas shadows camera={...} gl={{ antialias: true }}>
      <MujocoPhysics config={config}>
        <MyController />
      </MujocoPhysics>
      <OrbitControls />
      <EffectComposer>...</EffectComposer>
    </Canvas>
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Building Controllers" icon="gamepad" href="/guides/building-controllers">
    Custom controllers, IK solvers, and the `createController` factory
  </Card>

  <Card title="Installation" icon="download" href="/installation">
    Peer dependencies, bundler setup, and WASM notes
  </Card>

  <Card title="Architecture" icon="sitemap" href="/architecture">
    Provider → Canvas → children pattern and physics loop
  </Card>

  <Card title="Loading Models" icon="file-code" href="/loading-models">
    SceneConfig, Menagerie, custom model sources
  </Card>
</CardGroup>