Installation

Install mujoco-react and its peer dependencies

Install

npm install mujoco-react @react-three/fiber @react-three/drei three

Peer Dependencies

Package	Version	Purpose
@react-three/fiber	>=8	React renderer for Three.js
@react-three/drei	>=9	R3F helpers (PivotControls, etc.)
three	>=0.180	3D rendering
react	>=18	React

@mujoco/mujoco is installed by mujoco-react as the underlying MuJoCo WASM engine.

TypeScript

npm install -D @types/three

mujoco-react ships with full TypeScript types. No @types/ package needed for the library itself.

Bundler Setup

Vite (Recommended)

@mujoco/mujoco ships a .wasm asset. Vite serves package WASM assets correctly with the standard React setup:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
});

Next.js

Since MuJoCo uses WASM and browser APIs, it must run client-side only:

import dynamic from "next/dynamic";

const MujocoApp = dynamic(() => import("./MujocoApp"), { ssr: false });

Create React App

Works out of the box. No additional configuration needed.

Multi-Threaded WASM

MujocoProvider defaults to the single-threaded official MuJoCo WASM build. To opt into the official multi-threaded build:

import loadMujocoMt from "@mujoco/mujoco/mt";
import mtWasmUrl from "@mujoco/mujoco/mt/mujoco.wasm?url";

<MujocoProvider
  wasmVariant="auto"
  threadedLoader={loadMujocoMt}
  mtWasmUrl={mtWasmUrl}
>
  <App />
</MujocoProvider>

"auto" only loads the threaded build when threadedLoader and mtWasmUrl are provided and the browser reports globalThis.crossOriginIsolated === true. If you force wasmVariant="threaded", your dev server and production host must send:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Verify Installation

import { MujocoProvider, MujocoCanvas } from "mujoco-react";

function App() {
  return (
    <MujocoProvider>
      <MujocoCanvas
        config={{
          src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
          sceneFile: "scene.xml",
        }}
        style={{ width: "100%", height: "100vh" }}
        onReady={({ api }) => {
          console.log("MuJoCo loaded!", api.getBodies().map(({ name }) => name));
        }}
        onError={(err) => console.error("Load failed:", err)}
      >
        <ambientLight />
      </MujocoCanvas>
    </MujocoProvider>
  );
}

If you see a Franka Panda robot in your browser, everything is working.

The first load may take a few seconds as the WASM module initializes and model assets are fetched from GitHub. Subsequent loads are faster due to browser caching.