Skip to Content
Home

@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

NeedStart hereKey
Display a model with orbit controlsSimpleModelViewer None, including production
Configure products, annotations, animations or custom controlsModelViewer Required
Compare two modelsCompareViewer Required
Let your team edit a hosted scene and embed itContent 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

Quick Install

npm install @liveroom-tech/react-immersive three@^0.184.0 @react-three/fiber@^9.6.1

Import 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

exports.ts
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.