`@liveroom-tech/react-immersive`

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.

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 shadows prop
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 @react-three/fiber

pnpm


pnpm add @liveroom-tech/react-immersive three @react-three/fiber

yarn


yarn add @liveroom-tech/react-immersive three @react-three/fiber

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


import {
  BindingBuilder,
  material,
  ModelViewer,
  patchBindings,
  patchSceneConfig,
  SimpleModelViewer,
  useObjectBinding,
  useObjectBindings,
  useSceneConfig,
  useViewerActions,
  useViewerAnimations,
  useViewerEffects,
  useViewerCamera,
  useViewerConnection,
  useViewerHover,
  useViewerModel,
  useViewerSelection,
} from "@liveroom-tech/react-immersive";

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.

@liveroom-tech/react-immersive