Build with React Immersive
This guide targets @liveroom-tech/react-immersive 5.2.0. Use React and
React DOM 19, Three.js 0.184, and React Three Fiber 9.6.1 or a compatible
9.x release.
Read only what the task needs
- Compact agent index
- This guide as Markdown
- Version, peers, page and section URLs
- Full documentation bundle , optional and large
- Public source and runnable starters
Every documentation page has a .md alternative. The manifest also lists small
Markdown sections of the ModelViewer reference so you can fetch one topic
without loading the entire API reference. HTML is the default response;
Accept: text/markdown requests the Markdown alternative at the same docs URL.
Choose a component
| Goal | Import | Stylesheet | Runtime key prop |
|---|---|---|---|
| Display a model, inspect meshes, toggle visibility | SimpleModelViewer from @liveroom-tech/react-immersive/simple-model-viewer | @liveroom-tech/react-immersive/simple-model-viewer.css | None |
| Configure materials, actions, annotations, camera or app state | ModelViewer from @liveroom-tech/react-immersive | @liveroom-tech/react-immersive/styles.css | Required |
| Author bindings and scene settings visually | BindingBuilder from @liveroom-tech/react-immersive/binding-builder | @liveroom-tech/react-immersive/binding-builder.css | Required |
The package is proprietary. SimpleModelViewer needs no key or paid plan, including in production. For ModelViewer and BindingBuilder, follow the licensing guide before deployment. Account sign-in, plan selection and key creation are manual steps in the console .
Get a first render
Use the complete Vite setup
or Next.js App Router setup .
Both start with SimpleModelViewer and an explicitly sized container. The
public sample is red_room.glb ;
place it at public/red_room.glb in the consuming application.
Success means the model is visible, the scene objects panel lists objects,
and onModelLoaded fires. A successful TypeScript build alone does not verify
that a model URL works in the browser.
Add interaction
Start with ModelViewer without objectBindings to generate bindings for all
meshes. Use useViewer and spread viewer.props onto the component to connect
its controllers. Use onObjectCatalog to discover actual object identifiers;
do not invent node names. Duplicate authored names receive suffixed IDs.
When using defineObjectBindings, preserve literal IDs for authoring but widen
mutable React state to Record<string, ObjectBinding>. Bindings are indexed by
model node identifiers; binding.id is application metadata and can differ.
| Task | Read |
|---|---|
| Wire app state and controllers | useViewer |
| Materials, visibility, grouped edits | useObjectBindings |
| Camera focus and saved views | useViewerCamera |
| Lighting, environment and scene configuration | useSceneConfig |
| Animations | useViewerAnimations |
| Annotation tours, exports, XR or performance | ModelViewer section index |
| Export/import scene files | BindingBuilder |
| API shapes | Types |
| A complete feature implementation | Examples |
Verify the result
- Run the application’s typecheck and production build.
- Open the page in a browser with WebGL support.
- Confirm the model URL returns model data rather than an HTML error page.
- Confirm the viewer has height and its own stylesheet is imported.
- Confirm model-loaded/error callbacks and one intended interaction.
- For licensed components, check the key and the deployed domain against the plan.
If any step fails, use Troubleshooting . For existing projects, read the version and migration notes .