React HUD

In vgai, React is for the HUD/overlay only — not gameplay objects. You mount a React tree into the game’s UI container and tear it down on dispose.

The pointer-events model.

mountUI

mountUI(container, element) (packages/editor/template/src/examples/ui/mount-ui.ts) creates a React root and renders into it, returning an unmount function:

const unmount = mountUI(ctx.uiContainer, <MyHUD />);
// in dispose():
return { dispose: unmount };

Store the returned function and call it in your example’s dispose() so the HUD is removed on scene change.

The pointer-events model

ctx.uiContainer is a full-screen overlay created with pointer-events: none (packages/engine/src/runtime/create-runtime.ts), so clicks fall through to the 3D canvas by default. Interactive widgets explicitly set pointer-events: auto to receive input (the shared Panel, for instance, sets pointerEvents: 'auto').

Shared UI primitives

The template ships reusable, inline-styled HUD components in packages/editor/template/src/examples/ui/: Panel, Button, Slider, Toggle, KeyHint, and StatusDot. They use inline styles (no CSS files) and a dark, monospace aesthetic.

Plain Three.js for non-interactive UI

Static scenery, lights, and purely visual elements should be plain Three.js objects — only reach for React when you need DOM/HUD widgets.

For authoring UI visually (layout, theming, data binding) rather than hand-coding it, see the Visual UI Editor.

See also

• Visual UI Editor — build HUDs by direct manipulation.
• Design philosophy — why React is HUD-only.