@liveroom-tech/react-immersive
Requires React 19. Compatibility and upgrade notes .
AI Agent Guide · Markdown index · Vite setup · Next.js setup .
A React 3D model viewer for interactive 3D assets, mesh selection, object bindings, built-in UI panels, and a full suite of hooks for camera, animations, visibility, and more.
Choose your starting point
| Need | Start here | Key |
|---|---|---|
| Display a model with orbit controls | SimpleModelViewer | None, including production |
| Configure products, annotations, animations or custom controls | ModelViewer | Required |
| Compare two models | CompareViewer | Required |
| Let your team edit a hosted scene and embed it | Content editing workflow | Hosted project owner’s plan |
For a free embed in a React app, start with the dedicated entry point:
import { SimpleModelViewer } from "@liveroom-tech/react-immersive/simple-model-viewer";
import "@liveroom-tech/react-immersive/simple-model-viewer.css";
export function ModelEmbed() {
return <div style={{ height: 400 }}><SimpleModelViewer modelUrl="/model.glb" /></div>;
}Features
- GLB/GLTF, OBJ/MTL, FBX, USDZ, STL, and PLY rendering via React Three Fiber
- 3D Tiles streaming for large processed scenes, with object catalogs and configurable client caching
- Mesh selection by object name with built-in side panels
- Object bindings, drive transforms, color, texture, visibility, and actions from a plain data record
- Object move & rotate controls, geometry-centered handles with World or Local axis alignment
- Shadows & post-processing, soft shadows (auto-tuned for interiors), SSAO, bloom, and ACES tone mapping, toggleable via the
shadowsprop - Orbit and pointer-lock camera modes, camera movement limits, auto-rotation, and load-progress callbacks
- SimpleModelViewer, a lightweight model inspection viewer with no bindings or actions
- BindingBuilder, browser-based design-time tool for generating bindings and positioning model objects
- Hooks API:
Quick Install
npm
npm install @liveroom-tech/react-immersive three@^0.184.0 @react-three/fiber@^9.6.1Import the library stylesheet once from your application root:
import "@liveroom-tech/react-immersive/styles.css";Minimal Example
import objectBindings from "./objectBindings.json";
import {
ModelViewer,
type ObjectBinding,
} from "@liveroom-tech/react-immersive";
const initialBindings = objectBindings as Record<string, ObjectBinding>;
export default function App() {
return (
<div style={{ height: "100vh" }}>
<ModelViewer
modelUrl="/model.glb"
licenseKey="your-license-key"
objectBindings={initialBindings}
/>
</div>
);
}Without objectBindings, the viewer generates a binding for every mesh when the
model loads. To choose which objects are interactive and what they do, author
the bindings by hand, or generate starter bindings in BindingBuilder and export them as
objectBindings.json or a TypeScript file to import into your app.
UI styles ship as an explicit static CSS import; the package does not inject runtime style tags. Tailwind is not required in the consuming app.
Quick Inspection With SimpleModelViewer
If you don’t need objectBindings-driven styling and actions, SimpleModelViewer gives you a lightweight viewer for inspecting GLB, GLTF, OBJ, FBX, USDZ, STL, or PLY assets. It can also run in an upload-first mode for ad-hoc local model inspection:
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" />
</div>
);
}Exports
import {
material,
ModelViewer,
patchBindings,
patchSceneConfig,
useObjectBinding,
useObjectBindings,
useSceneConfig,
useViewerActions,
useViewerAnimations,
useViewerEffects,
useViewerCamera,
useViewerConnection,
useViewerHover,
useViewerModel,
useViewerSelection,
} from "@liveroom-tech/react-immersive";
import { SimpleModelViewer } from "@liveroom-tech/react-immersive/simple-model-viewer";
import { BindingBuilder } from "@liveroom-tech/react-immersive/binding-builder";Pure data helpers such as defineObjectBindings, patchBindings,
patchSceneConfig, and selectBindings are also available from the
server-safe @liveroom-tech/react-immersive/utils entry point. The main entry
continues to export them for backwards compatibility.