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

# MujocoCanvas

> R3F Canvas wrapper with physics simulation

A thin wrapper around React Three Fiber's `<Canvas>` that sets up the physics simulation. Accepts all standard R3F Canvas props plus MuJoCo-specific configuration.

## Usage

```tsx theme={null}
import { useRef } from "react";
import { MujocoProvider, MujocoCanvas } from "mujoco-react";
import type { MujocoSimAPI } from "mujoco-react";
import { OrbitControls } from "@react-three/drei";

function App() {
  const apiRef = useRef<MujocoSimAPI>(null);

  return (
    <MujocoProvider>
      <MujocoCanvas
        ref={apiRef}
        config={{
          src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
          sceneFile: "scene.xml",
        }}
        camera={{ position: [2, -1.5, 2.5], up: [0, 0, 1], fov: 45 }}
        shadows
        paused={false}
        speed={1.0}
        style={{ width: "100%", height: "100vh" }}
      >
        <OrbitControls makeDefault />
        <ambientLight intensity={0.7} />
      </MujocoCanvas>
    </MujocoProvider>
  );
}
```

## Props

### MuJoCo Props

<ParamField body="config" type="SceneConfig" required>
  Scene configuration — robot ID, model file, joints, etc. See [Loading Models](/loading-models).
</ParamField>

<ParamField body="onReady" type="({ api }) => void">
  Fires when the model is loaded and simulation is ready. Receives the full API object.
</ParamField>

<ParamField body="onError" type="(error: Error) => void">
  Called if model loading or simulation fails.
</ParamField>

<ParamField body="onStep" type="({ time, model, data }) => void">
  Called after each physics step with the current simulation time.
</ParamField>

<ParamField body="onSelection" type="({ bodyId, name }) => void">
  Fired when a body is double-clicked in the scene.
</ParamField>

### Physics Props

<ParamField body="paused" type="boolean" default="false">
  Pause/resume the simulation declaratively.
</ParamField>

<ParamField body="speed" type="number" default="1.0">
  Simulation speed multiplier. `0.5` = half speed, `2.0` = double speed.
</ParamField>

<ParamField body="gravity" type="[number, number, number]">
  Override gravity vector (m/s^2). Default: model's gravity.
</ParamField>

<ParamField body="timestep" type="number">
  Override simulation timestep (seconds). Default: model's timestep.
</ParamField>

<ParamField body="substeps" type="number">
  Number of physics substeps per frame for improved stability.
</ParamField>

<ParamField body="interpolate" type="boolean" default="false">
  Smooth rendered body poses between fixed physics steps. Useful for high-refresh displays.
</ParamField>

<ParamField body="renderOptions" type="MujocoRenderOptions">
  Optional render-time settings for generated MuJoCo geometry. Set
  `renderOptions={{ meshNormalSmoothing: true }}` to weld duplicate mesh
  vertices before recomputing normals, which smooths faceted STL visuals. Leave
  it unset when you need exact policy-render parity.
</ParamField>

<ParamField body="hiddenBodies" type="readonly string[]">
  Names of model bodies whose geometry should not be rendered. The bodies stay
  in the compiled model and keep simulating — only their meshes are skipped at
  scene-build time, so body, joint, and actuator indices are unchanged. The set
  is reapplied on every render rebuild, so toggling names can never be lost to a
  scene rebuild. Use it to show one arm of a bimanual model, hide fixtures, etc.
</ParamField>

### R3F Canvas Props

All standard `@react-three/fiber` Canvas props are passed through:

```tsx theme={null}
<MujocoCanvas
  camera={{ position: [2, 2, 2], fov: 45, up: [0, 0, 1] }}
  shadows
  dpr={[1, 2]}
  gl={{ antialias: true }}
  style={{ width: "100%", height: "100vh" }}
  className="my-canvas"
>
```

## Ref

`MujocoCanvas` forwards its ref as a `MujocoSimAPI` handle — the same object passed to `onReady`:

```tsx theme={null}
const apiRef = useRef<MujocoSimAPI>(null);

<MujocoCanvas ref={apiRef} config={config}>
  {/* ... */}
</MujocoCanvas>

// Later: apiRef.current?.reset()
```

## Notes

* Must be a child of `<MujocoProvider>`
* Children can use all mujoco-react hooks (`useMujoco`, `useBeforePhysicsStep`, etc.)
* The `config` prop is read on mount and when `api.loadScene()` is called — changing it after mount has no effect