MujocoProvider

WASM module lifecycle provider

The outermost wrapper that loads the MuJoCo WASM module and provides it to all children.

Usage

import { MujocoProvider } from "mujoco-react";

function App() {
  return (
    <MujocoProvider>
      <MujocoCanvas config={config}>
        {/* ... */}
      </MujocoCanvas>
    </MujocoProvider>
  );
}

Props

children · React.ReactNode · required

Child components that need access to MuJoCo.

onError · (error: Error) => void

Called if the WASM module fails to load.

wasmUrl · string

Custom URL for the single-threaded .wasm asset.

mtWasmUrl · string

Custom URL for the multi-threaded .wasm asset.

threadedLoader · (options?) => Promise<unknown>

Optional loader imported from @mujoco/mujoco/mt. It is supplied by apps that opt into threaded WASM.

wasmVariant · "single" | "threaded" | "auto"

MuJoCo WASM build to load. Defaults to "single". "auto" selects the threaded build only when threadedLoader and mtWasmUrl are provided and the page is cross-origin isolated.

timeout · number

WASM initialization timeout in milliseconds.

Threaded WASM

The official @mujoco/mujoco package includes a multi-threaded WASM build in addition to the default single-threaded build. Import it only in apps that opt into it:

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

<MujocoProvider
  wasmVariant="auto"
  threadedLoader={loadMujocoMt}
  threadCount={2}
  mtWasmUrl={mtWasmUrl}
>
  <MujocoCanvas config={config} />
</MujocoProvider>

Forced threaded mode requires browser cross-origin isolation headers:

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

useMujocoWasm Hook

Access the WASM module status from any child component:

import { useMujocoWasm } from "mujoco-react";

function LoadingIndicator() {
  const { mujoco, status, error } = useMujocoWasm();

  if (status === "loading") return <div>Loading WASM...</div>;
  if (status === "error") return <div>Error: {error}</div>;
  // mujoco is now available
  return null;
}

Return Value

Field	Type	Description
mujoco	MujocoModule | null	The raw WASM module, or null while loading
status	'loading' | 'ready' | 'error'	Current lifecycle state
error	string | null	Error message if loading failed

Notes

• Must wrap any component that uses MujocoCanvas or mujoco-react hooks
• The WASM module is loaded once on mount from @mujoco/mujoco. The package ships the JavaScript bindings and .wasm asset.
• Loading typically takes 1-3 seconds on first visit; subsequent visits use the browser cache

threadCount defaults to 0. Set a positive integer to initialize mju_threadpool for each simulation data instance. It requires the threaded build and cross-origin isolation. Loading the MT build alone does not request a simulation thread pool. Benchmark your scene before increasing the count; small scenes can be slower.