@liveroom/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 rendering via React Three Fiber and @react-three/drei
• Mesh selection by object name with built-in side panels
• Object bindings — drive color, texture, visibility, and actions from a plain data record
• Shadows & post-processing — soft shadows (auto-tuned for interiors), SSAO, bloom, and ACES tone mapping, toggleable via the shadows prop
• SimpleModelViewer — a lightweight GLB/GLTF inspection viewer with no objectBindings required
• BindingBuilder — browser-based design-time tool for generating starter bindings from GLB/GLTF assets
• Hooks API:
  • useViewerCamera
  • useViewerAnimations
  • useViewerSelection
  • useViewerHover
  • useViewerModel
  • useViewerActions
  • useObjectBinding
  • useObjectVisibility
  • useShareableViewerState

Quick Install

npm install @liveroom/react-immersive

pnpm add @liveroom/react-immersive

yarn add @liveroom/react-immersive

Minimal Example

import objectBindings from "./objectBindings.json";
import {
  ModelViewer,
  type ObjectBinding,
} from "@liveroom/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>
  );
}

objectBindings is required. You can author it by hand, or generate starter bindings in BindingBuilder and export them as objectBindings.json or a TypeScript file to import into your 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 assets. It can also run in an upload-first mode for ad-hoc local model inspection:

import { SimpleModelViewer } from "@liveroom/react-immersive";
 
export default function App() {
  return (
    <div style={{ height: "100vh" }}>
      <SimpleModelViewer modelUrl="/model.glb" />
    </div>
  );
}

Exports

import {
  BindingBuilder,
  ModelViewer,
  SimpleModelViewer,
  useObjectBinding,
  useObjectVisibility,
  useViewerActions,
  useViewerAnimations,
  useViewerCamera,
  useViewerHover,
  useViewerModel,
  useViewerSelection,
} from "@liveroom/react-immersive";