<!-- Generated from index.mdx; edit the MDX source. -->

Package: @liveroom-tech/react-immersive
Canonical: https://react-immersive.liveroom.dev/docs

# `@liveroom-tech/react-immersive`

Requires **React 19**. [Compatibility and upgrade notes](https://react-immersive.liveroom.dev/docs/releases).

[AI Agent Guide](https://react-immersive.liveroom.dev/docs/agent-guide) · [Markdown index](https://react-immersive.liveroom.dev/llms.txt)
· [Vite setup](https://react-immersive.liveroom.dev/docs/frameworks/vite) · [Next.js setup](https://react-immersive.liveroom.dev/docs/frameworks/nextjs).

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](https://react-immersive.liveroom.dev/docs/reference/simple-model-viewer) | None, including production |
| Configure products, annotations, animations or custom controls | [ModelViewer](https://react-immersive.liveroom.dev/docs/reference/model-viewer) | Required |
| Compare two models | [CompareViewer](https://react-immersive.liveroom.dev/docs/reference/compare-viewer) | Required |
| Let your team edit a hosted scene and embed it | [Content editing workflow](https://react-immersive.liveroom.dev/docs/content-editing) | Hosted project owner's plan |

For a free embed in a React app, start with the dedicated entry point:

```tsx
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 `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**:
  - [`useViewer`](https://react-immersive.liveroom.dev/docs/hooks/use-viewer)
  - [`useViewerCamera`](https://react-immersive.liveroom.dev/docs/hooks/use-viewer-camera)
  - [`useViewerConnection`](https://react-immersive.liveroom.dev/docs/hooks/use-viewer-connection)
  - [`useViewerAnimations`](https://react-immersive.liveroom.dev/docs/hooks/use-viewer-animations)
  - [`useViewerEffects`](https://react-immersive.liveroom.dev/docs/hooks/use-viewer-effects)
  - [`useViewerSelection`](https://react-immersive.liveroom.dev/docs/hooks/use-viewer-selection)
  - [`useViewerHover`](https://react-immersive.liveroom.dev/docs/hooks/use-viewer-hover)
  - [`useViewerModel`](https://react-immersive.liveroom.dev/docs/hooks/use-viewer-model)
  - [`useViewerIsolation`](https://react-immersive.liveroom.dev/docs/hooks/use-viewer-isolation)
  - [`useViewerActions`](https://react-immersive.liveroom.dev/docs/hooks/use-viewer-actions)
  - [`useObjectBinding`](https://react-immersive.liveroom.dev/docs/hooks/use-object-binding)
  - [`useObjectBindingIds`](https://react-immersive.liveroom.dev/docs/hooks/use-object-binding-ids)
  - [`useObjectBindings`](https://react-immersive.liveroom.dev/docs/hooks/use-object-bindings)
  - [`useSceneConfig`](https://react-immersive.liveroom.dev/docs/hooks/use-scene-config)
  - [`useShareableViewerState`](https://react-immersive.liveroom.dev/docs/hooks/use-shareable-viewer-state)

## Quick Install


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



```bash
pnpm add @liveroom-tech/react-immersive three@^0.184.0 @react-three/fiber@^9.6.1
```



```bash
yarn add @liveroom-tech/react-immersive three@^0.184.0 @react-three/fiber@^9.6.1
```


Import the library stylesheet once from your application root:

```tsx
import "@liveroom-tech/react-immersive/styles.css";
```

## Minimal Example

```tsx
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`](https://react-immersive.liveroom.dev/docs/reference/binding-builder) 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`](https://react-immersive.liveroom.dev/docs/reference/simple-model-viewer) 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:

```tsx
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

```ts filename="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.
