@liveroom-tech/react-immersive
v6.2.3
Published
React-based 3D model viewer for interactive GLB, GLTF, OBJ, FBX, and USDZ assets, with mesh selection, object bindings, and a built-in design-time editor.
Maintainers
Readme
React Immersive — 3D model viewers for React
@liveroom-tech/react-immersive renders GLB/GLTF, OBJ, FBX, USDZ, STL, and PLY
assets in React. Use its components and hooks for mesh selection, materials,
visibility, camera control, animations, annotations, and scene authoring.
Requires React 19.
Documentation · AI Agent Guide · Markdown index · Examples · Public GitHub
Choose a component
| Need | Component and import | CSS import | Runtime key prop |
| --- | --- | --- | --- |
| Display/inspect a model and toggle mesh visibility | SimpleModelViewer from @liveroom-tech/react-immersive/simple-model-viewer | @liveroom-tech/react-immersive/simple-model-viewer.css | None |
| Interactive object bindings, materials, actions, tours, camera and app state | ModelViewer from @liveroom-tech/react-immersive | @liveroom-tech/react-immersive/styles.css | Required |
| Author and export bindings/scene configuration | BindingBuilder from @liveroom-tech/react-immersive/binding-builder | @liveroom-tech/react-immersive/binding-builder.css | Required |
Import each component's stylesheet once. Give the viewer's container an explicit height. The package does not require Tailwind in the consuming application.
SimpleModelViewer exposes a named region even with both panels disabled. Set
aria-label="Product preview" or aria-labelledby="product-heading" to give it
a model-specific name. Its default name is "3D model viewer", translated through
labels.modelViewer; collapsed panel buttons also have localized names.
Install
In a React 19 application:
npm install @liveroom-tech/react-immersive three@^0.184.0 @react-three/fiber@^9.6.1| Peer | Supported range |
| --- | --- |
| react | ^19.0.0 |
| react-dom | ^19.0.0 |
| three | ^0.184.0 |
| @react-three/fiber | ^9.6.1 |
The complete Vite and Next.js App Router guides include file locations, client boundaries, sample assets, TypeScript configuration and run/build instructions. Standalone starters live in the public examples repository.
First render
Place your asset at public/model.glb. In a Vite React application:
import "@liveroom-tech/react-immersive/simple-model-viewer.css";
import { SimpleModelViewer } from "@liveroom-tech/react-immersive/simple-model-viewer";
export default function App() {
return (
<div style={{ height: "100vh" }}>
<SimpleModelViewer
modelUrl="/model.glb"
onModelLoaded={(model) => console.log("Loaded", model.objectCount, "objects")}
onLoadError={(error) => console.error("Model failed to load", error)}
/>
</div>
);
}For Next.js, import CSS in app/layout.tsx and use the complete client component
from the Next.js guide.
The public Red Room sample
is by LaisLH, licensed under
CC BY 4.0; retain attribution.
Add interaction
ModelViewer generates bindings automatically when objectBindings is omitted.
Use useViewer to connect bindings, selection, camera, animations and other
controllers to one viewer:
"use client";
import { ModelViewer, useViewer } from "@liveroom-tech/react-immersive";
import "@liveroom-tech/react-immersive/styles.css";
export function InteractiveViewer({ licenseKey }: { licenseKey: string }) {
const viewer = useViewer();
return (
<div style={{ height: "100vh" }}>
<ModelViewer modelUrl="/model.glb" licenseKey={licenseKey} {...viewer.props} />
</div>
);
}See Getting Started
for a complete bindings example. Use onObjectCatalog or BindingBuilder to
obtain actual model-node identifiers. defineObjectBindings preserves literal
IDs; widen mutable React state to Record<string, ObjectBinding> when passing a
state setter to onObjectBindingsChange.
Pure data helpers, including defineObjectBindings, patchBindings,
patchSceneConfig, and selectBindings, are available from the server-safe
@liveroom-tech/react-immersive/utils entry.
To fly to an annotation and open its card from your own UI, call
await viewer.connection.goToAnnotation(annotationId). The numeric ID comes
from sceneConfig.annotations. It restores a saved camera view or frames the
marker automatically, and returns false before connection or for an unknown
or filtered-out ID. Controlled cards still use onActiveAnnotationChange.
Hotspot markers expose their annotation title as a tooltip and accessible name.
viewer.camera.focusObject(id, { padding: 0.2, paddingRight: 1 }) sets object-fit
padding in scene units. Per-side options override uniform padding; omitted
values keep the 0.5 default. Padding does not alter a binding's saved camera view.
With enableXR (or xr={{ enabled: true }}), an app-owned button can call
await viewer.connection.startAR(). Invoke it directly in the click handler
and catch launch errors. It starts WebXR AR when supported, otherwise launches
the supplied iOS USDZ or opens the configured-AR/phone handoff. It returns
false when disabled, unavailable, or not ready; true means the session
started or a platform handoff opened.
Embed a hosted project without React
For Shopify, WordPress, Webflow, or plain HTML, open a hosted project's Share menu, set General access to Anyone with the link, and choose Copy embed code. Paste that iframe into an HTML/embed block. No npm package or license key is needed on the parent page. The embed shows the saved viewer without editing or collaboration controls; restricted projects cannot be embedded.
<iframe
src="https://react-immersive.liveroom.dev/embed/projects/YOUR_PROJECT_ID"
title="Interactive 3D viewer"
width="100%"
height="600"
style="display:block;width:100%;height:600px;border:0;"
loading="lazy"
allow="fullscreen; xr-spatial-tracking"
allowfullscreen
></iframe>See Embedding outside React for platform instructions, sizing, updates, and access behavior.
Find the API for your task
- ModelViewer: props, bindings, materials, annotations, exports, XR, performance.
- SimpleModelViewer: inspection, uploads, lighting and callbacks.
- BindingBuilder: authoring, exports and import workflows.
- useViewer: connect controllers to the viewer.
- useObjectBindings: editable state, selectors, materials and visibility.
- useViewerCamera: camera focus, reset and saved views.
- useSceneConfig: lighting, environment and scene settings.
- Types and labels.
- Manifest: supported version/peers, all page URLs and small API section exports.
- Extended package reference: detailed examples retained from the former long README.
- Troubleshooting and migration notes.
License and keys
This is proprietary software, commercially maintained by Liveroom. The core
source is private; documentation, starters, issues and discussions are public.
See the package license,
also included as LICENSE in the npm package, and the
licensing guide.
ModelViewer and BindingBuilder require a runtime licenseKey. Create one in the
console. Local development and
production domains are governed by the selected plan. SimpleModelViewer has no
runtime key prop and needs no key or paid plan, including in production.
The remaining proprietary package terms still apply.
VITE_LICENSE_KEY and NEXT_PUBLIC_LICENSE_KEY are browser-visible values.
Use a key for the intended registered domain and keep keys out of public
repositories. Never put account credentials, payment tokens, or server API
secrets in client-exposed environment variables.
Support
Report reproducible issues with the package version, framework, browser and sanitized error text in the public issue tracker. Send private models, license/account requests and security reports to [email protected].
