@live_room/react-immersive

@live_room/react-immersive is a React-based 3D model viewer for interactive GLB/GLTF assets. It renders a model with React Three Fiber, lets users click named meshes, shows a built-in side panel for the selected object, and supports per-object actions such as color changes, texture uploads, and visibility toggles.

What It Does

The library currently exports:

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

It also exports types for ObjectBinding, ObjectBindingMaterial, ObjectActionEvent, SceneConfig, AnimationControls, and related shapes used throughout this document.

ModelViewer provides:

• GLB/GLTF model rendering through @react-three/fiber and @react-three/drei
• orbit/pan/zoom camera controls via CameraControls
• auto-fits the model on load, and re-fits when the canvas is resized (window resize, device rotation, or a panel opening/closing) — toggleable through refitOnResize to instead preserve the user's orbit/zoom
• optional custom scene lighting through a lights prop
• optional custom camera configuration through a camera prop
• optional custom background color through a backgroundColor prop
• optional shadow rendering toggle through a shadows prop (on by default)
• optional on-screen movement controller through showMouseController and its tuning props
• optional custom left object data panel through customObjectBindingDataPanel
• optional custom right scene objects panel through customSceneObjectsPanel
• optional hiding of either built-in panel through showObjectBindingDataPanel and showSceneObjectsPanel
• optional model export button through showDownloadButton and downloadFilename, plus independent showResetButton / showDownloadButtons toggles for the rest of that action bar
• click-to-measure distance tool and a bounding-box dimensions overlay through showMeasureTools and measurementUnit
• a guided-tour control cluster (Previous/Stop/Next) for stepping through annotations, toggleable via showAnnotationNavigation
• a sceneConfig prop accepting the same scene-wide config (lighting, environment, background, post-processing, animations, annotations) authored by BindingBuilder's Scene tab
• render-loop and perf tuning through renderMode, maxDpr, performanceProfile, and compressed-asset decoder options (dracoDecoderPath, ktx2TranscoderPath, meshopt)
• WebXR "View in your space" (AR) and "Enter VR" through enableXR, with tap-to-place, pinch-to-resize, and twist-to-rotate AR placement gestures
• mesh selection by object name
• a built-in left side panel for the selected object
• object-specific action buttons driven by objectBindings
• built-in color picking that commits the chosen hex into objectBindings.style.material.baseColor
• built-in texture upload that commits a URL into objectBindings.style.material.texture.path (blob URL by default, or a durable URL when onTextureUpload is provided)
• per-object MeshPhysicalMaterial overrides for metalness, roughness, emissive, normal/bump, AO, displacement, clearcoat, sheen, anisotropy, specular, transmission, thickness, reflectivity, sidedness, and limited blending modes
• per-object visibility toggling through objectBindings.visible
• hover and selected-state highlighting
• external selection state control through selectedObject and onObjectSelect
• hover callbacks through onObjectHover
• model-ready callbacks through onModelLoaded
• model-load error callbacks through onLoadError
• camera change callbacks through onCameraChange
• viewer-ready callbacks through onViewerReady
• action event callbacks through onAction
• animation playback for GLB/GLTF models with embedded animations through onAnimationsReady
• annotation marker callbacks through onAnnotationsChange and controlled/uncontrolled activeAnnotation / onActiveAnnotationChange

BindingBuilder provides:

• a design-time UI for generating starter bindings from GLB/GLTF assets, gated by licenseKey (see "BindingBuilder licensing & plan tiers" below)
• demo model loading or custom .glb, .gltf, or zipped GLTF upload
• editable binding fields for identity, basics, style, actions, metrics, metadata, and saved camera state
• a one-click material preset gallery (wood, metal, chrome, glass, plastic, fabric, ceramic, concrete, etc.)
• undo/redo for both the Object tab's bindings and the Scene tab's config, independently, with Cmd/Ctrl+Z / Cmd/Ctrl+Shift+Z shortcuts
• a Scene tab for the same sceneConfig shape ModelViewer accepts (lighting, environment, background, post-processing, animations, annotations)
• import a previously exported objectBindings.json or sceneConfig.json and merge it back onto the current model/config
• live preview using ModelViewer
• export as JSON or TypeScript — bundled into a .zip with a materials/ folder automatically when any texture field was filled by file upload, otherwise a plain file
• license-tier gating for some editor features (texture maps, environment lighting/backgrounds, wireframe preview, animation configuration, annotations, post-processing)

SimpleModelViewer provides:

• a lightweight GLB/GLTF viewer that does not require objectBindings and does not require a licenseKey
• optional local .glb, standalone/data-URI .gltf, or zipped GLTF upload mode for ad-hoc inspection without relying on the modelUrl asset
• built-in scene objects panel with search and visibility toggles
• a built-in environment/scene settings panel (background color, environment preset, auto-rotate, exposure, ambient + directional light) toggleable via showSceneSettingsPanel, with each control's initial value seedable via props
• click-to-select and fit-to-object focus behavior
• optional background color and model lifecycle callbacks
• a smaller API surface for simple inspection use cases

Installation

npm install @live_room/react-immersive

The component ships with its own internal UI styles through a CSS import. Tailwind is not required in the consuming app.

Peer dependencies:

• react >= 17
• react-dom >= 17

ModelViewer and BindingBuilder require a licenseKey at runtime (see licenseKey). Get one from the Developer Portal — see Resources below.

Resources

• Developer Portal — sign in, pick a plan, and generate a licenseKey
• Docs — full reference for every component, hook, and prop
• Live editor — try BindingBuilder in the browser without installing anything
• npm package

Quick Start

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

const initialBindings = {
  CarBody: {
    id: "car-body",
    modelObjectId: "CarBody",
    type: "body",
    label: "Car Body",
    selectable: true,
    hoverable: true,
    visible: true,
    style: {
      material: {
        texture: {
          path: "/materials/oak-wood.jpg",
        },
      },
    },
    metrics: {},
    metadata: {
      category: "exterior",
    },
    actions: [
      { id: "change-color", label: "Change Color", type: "command" },
      { id: "change-material", label: "Change Material", type: "command" },
      { id: "toggle-visibility", label: "Toggle Visibility", type: "command" },
    ],
  },
};

export default function Example() {
  const [objectBindings, setObjectBindings] = useState(initialBindings);
  const { selectedObjectBinding, handleObjectSelect } = useViewerSelection();
  const { hoveredObjectBinding, handleHoveredObject } = useViewerHover();
  const {
    cameraState,
    resetView,
    focusObject,
    fitScene,
    setCameraTarget,
    handleCameraChange,
    handleViewerReady,
  } = useViewerCamera();
  const {
    isLoading,
    isReady,
    error,
    bounds,
    objectCount,
    handleModelLoaded,
    handleLoadError,
  } = useViewerModel();
  const { hiddenObjects, toggleObjectVisibility } = useObjectVisibility(
    objectBindings,
    setObjectBindings,
  );
  const { getActionsForObject, runAction } = useViewerActions(objectBindings, {
    onAction: (event) => {},
    onObjectBindingsChange: setObjectBindings,
  });
  const focusedBinding = useObjectBinding(objectBindings, "car-body");

  return (
    <div style={{ height: "100vh", overflow: "hidden" }}>
      <ModelViewer
        modelUrl="/model.glb"
        licenseKey="your-license-key"
        objectBindings={objectBindings}
        selectedObject={selectedObjectBinding}
        onObjectSelect={handleObjectSelect}
        onObjectHover={handleHoveredObject}
        onCameraChange={handleCameraChange}
        onModelLoaded={handleModelLoaded}
        onLoadError={handleLoadError}
        onObjectBindingsChange={setObjectBindings}
        onViewerReady={handleViewerReady}
        onAction={(event) => {}}
      />

      <button onClick={() => toggleObjectVisibility("car-body")}>
        Toggle Visibility
      </button>
      <button onClick={() => runAction("car-body", "toggle-visibility")}>
        Run visibility action
      </button>
      <button onClick={() => resetView()}>Reset view</button>
      <button onClick={() => focusObject("car-body")}>Focus Object</button>
      <button onClick={() => fitScene()}>Fit scene</button>
      <button onClick={() => setCameraTarget([0, 0, 0])}>Target origin</button>
      <pre>{JSON.stringify(getActionsForObject("car-body"), null, 2)}</pre>
      <pre>{JSON.stringify(cameraState, null, 2)}</pre>
      <pre>
        {JSON.stringify(
          { isLoading, isReady, error, bounds, objectCount },
          null,
          2,
        )}
      </pre>
      <pre>{JSON.stringify(hiddenObjects, null, 2)}</pre>
      <pre>{JSON.stringify(hoveredObjectBinding, null, 2)}</pre>
      <pre>{JSON.stringify(focusedBinding, null, 2)}</pre>
    </div>
  );
}

If you want a simple helper for selection state, the library also exports:

const {
  selectedObjectBinding,
  setSelectedObjectBinding,
  handleObjectSelect,
  clearSelection,
} = useViewerSelection();

If you want to resolve a binding from an object identifier, the library also exports:

const binding = useObjectBinding(objectBindings, "car-body");

useObjectBinding checks, in order:

• the object binding map key
• binding.id
• binding.modelObjectId

If you want a flat list of every modelObjectId across your bindings, the library also exports:

const ids = useObjectBindingIds(objectBindings);
// → ["CarBody", "WheelFL", "WheelFR", ...]

If you want to control object visibility outside the viewer, the library also exports:

const [objectBindings, setObjectBindings] = useState(initialBindings);

const {
  hiddenObjects,
  hiddenObjectIds,
  hideObject,
  showObject,
  toggleObjectVisibility,
  isObjectHidden,
  clearHiddenObjects,
} = useObjectVisibility(objectBindings, setObjectBindings);

<ModelViewer
  modelUrl="/model.glb"
  licenseKey="your-license-key"
  objectBindings={objectBindings}
  onObjectBindingsChange={setObjectBindings}
/>;

useObjectVisibility is a stateless utility hook. It does not own its own copy of objectBindings — the consumer owns the state and passes both the current value and its setter. The hook's methods (hideObject, showObject, etc.) call the setter directly, so there is no risk of the hook and the viewer drifting out of sync.

It accepts either:

• the object binding map key
• binding.id
• binding.modelObjectId

and returns:

• hiddenObjects: a derived map of hidden binding keys
• hiddenObjectIds: the currently hidden binding IDs
• hideObject, showObject, toggleObjectVisibility
• isObjectHidden
• clearHiddenObjects

If you want to keep hover state in sync with the viewer, the library also exports:

const { hoveredObjectBinding, handleHoveredObject } = useViewerHover();

<ModelViewer
  modelUrl="/model.glb"
  licenseKey="your-license-key"
  objectBindings={objectBindings}
  onObjectHover={handleHoveredObject}
/>;

useViewerHover returns:

• hoveredObjectBinding: the currently hovered binding or null
• handleHoveredObject: a callback you can pass directly to onObjectHover

If you want model lifecycle and scene metadata, the library also exports:

const {
  isLoading,
  isReady,
  error,
  bounds,
  objectCount,
  handleModelLoaded,
  handleLoadError,
} = useViewerModel();

<ModelViewer
  modelUrl="/model.glb"
  licenseKey="your-license-key"
  objectBindings={objectBindings}
  onModelLoaded={handleModelLoaded}
  onLoadError={handleLoadError}
/>;

useViewerModel returns:

• isLoading: true until the model has loaded or failed
• isReady: true after a successful model load
• error: the most recent load/render error, or null
• bounds: the loaded scene bounds as min, max, center, and size
• objectCount: the number of mesh objects in the loaded scene
• handleModelLoaded: a callback you can pass directly to onModelLoaded
• handleLoadError: a callback you can pass directly to onLoadError

If you want to inspect or trigger binding actions programmatically, the library also exports:

const { getActionsForObject, runAction } = useViewerActions(objectBindings, {
  onAction: (event) => {},
  onObjectBindingsChange: setObjectBindings,
});

const actions = getActionsForObject("car-body");
runAction("car-body", "toggle-visibility");

useViewerActions returns:

• getActionsForObject: resolves the actions configured for a binding by key, binding.id, or binding.modelObjectId
• runAction: dispatches an ObjectActionEvent and returns it, or null if the binding or action cannot be found

Current note:

• visibility-style actions (toggle-visibility) update binding data through onObjectBindingsChange
• color/material actions still rely on ModelViewer's built-in UI popovers, so runAction dispatches those events but does not open the internal color picker or texture upload popover by itself

BindingBuilder

BindingBuilder is an exported design-time helper component for authoring objectBindings in the browser.

Basic usage:

import { BindingBuilder } from "@live_room/react-immersive";

export default function App() {
  return <BindingBuilder licenseKey="your-license-key" />;
}

BindingBuilder accepts one required prop:

type BindingBuilderProps = {
  licenseKey: string;
};

licenseKey is validated the same way as ModelViewer's (see licenseKey below). While the key is being checked, BindingBuilder renders a "Verifying license…" placeholder; if it's invalid, it renders an error message instead of the editor.

Current behavior — Object tab:

• load the bundled demo model or upload a .glb, standalone/data-URI .gltf, or .zip containing a .gltf plus its referenced .bin and texture files
• traverse renderable mesh nodes and generate starter bindings automatically
• edit binding identity, label, type, status, booleans, style, actions, metrics, metadata, and saved camera state
• apply a one-click material preset (wood, metal, chrome, glass, plastic, fabric, ceramic, concrete, etc.) onto the selected object's material
• undo/redo the current bindings (toolbar buttons or Cmd/Ctrl+Z / Cmd/Ctrl+Shift+Z); rapid edits coalesce into a single undo step
• import a previously exported objectBindings.json, merged onto the current model by modelObjectId
• export the current bindings as JSON or TypeScript — bundled into a .zip (with a materials/ folder) when any texture field was filled by uploading a file, otherwise a plain file

Current behavior — Scene tab:

• configure the same SceneConfig shape ModelViewer's sceneConfig prop accepts (lighting, environment, background, ground shadows, wireframe, post-processing, animations, annotations)
• undo/redo the scene config independently of the Object tab's bindings history
• import a previously exported sceneConfig.json, merged by top-level section
• export the current scene config as JSON or TypeScript

Preview:

• the selected node previews live in an embedded ModelViewer

BindingBuilder licensing & plan tiers

Some editor features are gated by the license's plan tier (the server-returned tier, normalized to "free" | "starter" | "growth"):

| Tier | Unlocks | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | free | All 3 components are available. SimpleModelViewer is fully available, while ModelViewer and BindingBuilder are limited to local development with base color, metalness/roughness sliders, and basic scene settings only | | starter | + Texture maps, the specular workflow, reflectivity, environment lighting, environment backgrounds, wireframe preview, animation configuration, annotations | | growth | + Post-processing effects |

A locked feature renders in place (not hidden) with a message naming the required plan, so it stays discoverable while editing.

SimpleModelViewer

SimpleModelViewer is an exported lightweight viewer for cases where you want to load a GLB/GLTF asset, inspect meshes, and toggle visibility without building objectBindings. It can either load a fixed modelUrl or, when enableModelUpload is turned on, let the user drag-and-drop or choose a local model at runtime.

Basic usage:

import { SimpleModelViewer } from "@live_room/react-immersive";

export default function App() {
  return (
    <div style={{ height: "100vh" }}>
      <SimpleModelViewer modelUrl="/model.glb" />
    </div>
  );
}

SimpleModelViewer does not take a licenseKey — licensing is enforced by ModelViewer and BindingBuilder only.

Sizing note:

• SimpleModelViewer fills the width and height of its parent container
• give the parent an explicit height (for example 100vh, 480px, or a Tailwind class like h-[100px]) when you want a fixed viewer height

Current behavior:

• discovers renderable meshes directly from the loaded GLB/GLTF scene
• renders a right-side scene objects panel with search and visibility toggles
• renders a left-side environment/scene settings panel (background color, environment preset, auto-rotate, exposure, ambient + directional light) toggleable via showSceneSettingsPanel, with every control seedable via props
• optionally replaces modelUrl with a drag-and-drop / file-picker flow when enableModelUpload is enabled
• lets users click a mesh or panel row to select and focus it
• fits the full scene on initial load
• uses built-in ambient, directional, and environment lighting

Use SimpleModelViewer when you want a quick inspection viewer. Use ModelViewer when you need binding-driven styling, actions, metadata, custom panels, exports, or animation integrations.

If you want camera state and imperative camera helpers, the library also exports:

const {
  cameraState,
  resetView,
  focusObject,
  fitScene,
  setCameraTarget,
  handleCameraChange,
  handleViewerReady,
} = useViewerCamera();

<ModelViewer
  modelUrl="/model.glb"
  licenseKey="your-license-key"
  objectBindings={objectBindings}
  onCameraChange={handleCameraChange}
  onViewerReady={handleViewerReady}
/>;

useViewerCamera returns:

• cameraState: the latest camera position, target, fov, and zoom
• resetView: resets the controls to their initial saved state
• focusObject: fits the camera to a binding by key, binding.id, or binding.modelObjectId
• fitScene: fits the camera to the whole loaded scene
• setCameraTarget: sets the camera target to a given [x, y, z]
• setCameraState: restores a full camera state (position/target/fov/zoom) previously read from cameraState
• handleCameraChange: a callback you can pass directly to onCameraChange
• handleViewerReady: a callback you can pass directly to onViewerReady

If your GLB/GLTF model contains animations, the library also exports:

const {
  clips,
  currentClip,
  isPlaying,
  speed,
  play,
  pause,
  stop,
  setSpeed,
  handleAnimationsReady,
} = useViewerAnimations();

<ModelViewer
  modelUrl="/character.glb"
  licenseKey="your-license-key"
  objectBindings={objectBindings}
  onAnimationsReady={handleAnimationsReady}
/>;

useViewerAnimations returns:

• clips: an array of animation clip names found in the GLB/GLTF file
• clipDetails: clip metadata including sourceName and duration in seconds
• currentClip: the name of the currently playing clip, or null
• isPlaying: true while an animation is playing (not paused or stopped)
• speed: the current playback speed (default 1)
• time: the live playback position of the current clip, in seconds (updates while playing)
• duration: the length of the current clip, in seconds
• play: starts a clip by name; if the same clip is paused, resumes it instead of restarting
• pause: pauses the currently playing clip at its current time
• stop: stops the current clip and resets it
• setSpeed: changes the playback speed (e.g. 0.5 for half speed, 2 for double)
• seek: scrubs the current clip to an absolute time in seconds (works while playing or paused), clamped to the clip length
• handleAnimationsReady: a callback you can pass directly to onAnimationsReady

Example with playback controls:

const { clips, currentClip, isPlaying, play, pause, stop, setSpeed } =
  useViewerAnimations();

// Play/pause toggle
<button onClick={() => (isPlaying ? pause() : play(currentClip ?? clips[0]))}>
  {isPlaying ? "Pause" : "Play"}
</button>

// Stop
<button onClick={stop}>Stop</button>

// Speed slider
<input
  type="range"
  min="0.1"
  max="3"
  step="0.1"
  defaultValue="1"
  onChange={(e) => setSpeed(Number(e.target.value))}
/>

// Clip selector
{clips.map((name) => (
  <button key={name} onClick={() => play(name)}>
    {name} {currentClip === name && isPlaying ? "▶" : ""}
  </button>
))}

Public API

The source code currently defines ModelViewer with these props:

type Props = {
  modelUrl: string;
  licenseKey: string;
  objectBindings: Record<string, ObjectBinding>;
  selectedObject?: ObjectBinding | null;
  onObjectBindingsChange?: (next: Record<string, ObjectBinding>) => void;
  onObjectSelect?: (binding: ObjectBinding | null) => void;
  onObjectHover?: (binding: ObjectBinding | null) => void;
  onModelLoaded?: (scene: Object3D) => void;
  onLoadError?: (error: unknown) => void;
  onAction?: (event: ObjectActionEvent) => void;
  onHiddenObjectsChange?: (next: Record<string, boolean>) => void;
  onCameraChange?: (camera: Camera, controls: CameraControls) => void;
  onViewerReady?: (viewer: ViewerReadyState) => void;
  onTextureUpload?: (file: File, objectId: string) => Promise<string>;
  onAnimationsReady?: (controls: AnimationControls) => void;
  onAnnotationsChange?: (annotations: AnnotationMarker[]) => void;
  activeAnnotation?: AnnotationMarker | null;
  onActiveAnnotationChange?: (annotation: AnnotationMarker | null) => void;
  lights?: React.ReactNode;
  camera?: React.ComponentProps<typeof Canvas>["camera"];
  backgroundColor?: string;
  shadows?: boolean;
  showObjectBindingDataPanel?: boolean;
  customObjectBindingDataPanel?: (
    props: CustomObjectBindingDataPanelProps,
  ) => React.ReactNode;
  customSceneObjectsPanel?: (
    props: CustomSceneObjectsPanelProps,
  ) => React.ReactNode;
  showSceneObjectsPanel?: boolean;
  showDownloadButton?: boolean;
  downloadFilename?: string;
  showResetButton?: boolean;
  showDownloadButtons?: boolean;
  showMouseController?: boolean;
  mouseControllerPosition?:
    | "bottom-left"
    | "bottom-right"
    | "top-left"
    | "top-right"
    | "center"
    | "center-bottom"
    | "center-top";
  mouseControllerOpacity?: number;
  moveSensitivity?: number;
  zoomSensitivity?: number;
  sceneConfig?: SceneConfig;
  disableZoom?: boolean;
  zoomOnSelected?: boolean;
  onAutoFit?: () => Promise<boolean>;
  refitOnResize?: boolean;
  renderMode?: "always" | "demand";
  maxDpr?: number;
  performanceProfile?: "auto" | "high" | "low";
  dracoDecoderPath?: string | false;
  ktx2TranscoderPath?: string | false;
  meshopt?: boolean;
  showMeasureTools?: boolean;
  measurementUnit?: string;
  enableXR?: boolean;
  usdzUrl?: string;
  showAnnotationNavigation?: boolean;
};

modelUrl

URL or public path to the .glb or .gltf model. For .gltf URLs with external .bin or texture files, those files must be hosted at the relative paths declared in the .gltf.

Example:

modelUrl = "/model.glb";

licenseKey

License key for the library. Required.

objectBindings

A map keyed by the model node name. Each key should match a mesh name from the GLB/GLTF file.

objectBindings is the single source of truth for all visual state. Changes to the binding record drive rendering:

• visible controls mesh visibility
• style.material.baseColor sets the mesh color (committed by the built-in color picker on close)
• style.material.texture.path sets the mesh texture (committed by the built-in texture upload; uses onTextureUpload for a durable URL when provided, otherwise a session-scoped blob URL)
• style.material.* applies per-object MeshPhysicalMaterial overrides such as emissive, metalness, roughness, opacity, clearcoat, sheen, anisotropy, specular, transmission, thickness, reflectivity, and sidedness
• cameraState.position and cameraState.target define the camera view to use when that object is focused or selected from the viewer UI

Example:

const objectBindings = {
  Object_2: {
    id: "obj-2",
    modelObjectId: "Object_2",
    type: "body",
    visible: true,
    cameraState: {
      position: [2.8, 1.6, 4.2],
      target: [0, 0.8, 0],
    },
    style: {
      material: {
        baseColor: "#ff0000",
        texture: {
          path: "/materials/body-finish.jpg",
        },
      },
    },
    actions: [
      { id: "change-color", label: "Change Color", type: "command" },
      { id: "change-material", label: "Change Material", type: "command" },
      { id: "toggle-visibility", label: "Toggle Visibility", type: "command" },
    ],
    metrics: {},
    metadata: {},
  },
};

selectedObject

Optional currently selected object binding, or null when nothing is selected.

If provided, ModelViewer behaves as a controlled component. If omitted, ModelViewer manages its own selection state internally.

When the selected object has a cameraState with both position and target, the viewer uses that saved camera view for focus/select behavior instead of falling back to fitToBox.

onObjectSelect

Optional callback called when the user clicks a mesh or closes the side panel.

Behavior:

• clicking a mesh calls onObjectSelect(binding)
• closing the panel calls onObjectSelect(null)
• clicking the same mesh again still selects it; selection is not toggled off automatically
• if the binding includes cameraState.position and cameraState.target, the viewer moves the camera to that saved view when focusing that object

onObjectHover

Optional callback called when the user hovers a mesh in the model.

Behavior:

• pointer over a mesh calls onObjectHover(binding)
• pointer out calls onObjectHover(null)

onHiddenObjectsChange

Optional callback fired with the derived hidden-object map whenever the current binding data changes hidden visibility state.

onObjectBindingsChange

Optional callback fired when the viewer's built-in UI updates binding data.

This fires for:

• visibility toggles (binding.visible)
• color picks (binding.style.material.baseColor) — committed when the color picker closes
• texture uploads (binding.style.material.texture.path) — committed immediately (via onTextureUpload when provided, otherwise as a blob URL)
• texture removal (binding.style.material.texture cleared)

If you want the viewer and your app state to stay in sync, pass objectBindings from state and wire this callback back into that state setter.

onModelLoaded

Optional callback fired after the GLB/GLTF scene has been loaded.

Current callback shape:

(scene: Object3D) => void

onLoadError

Optional callback fired if the model fails to load or render.

Current callback shape:

(error: unknown) => void

onAction

Optional callback fired when a built-in action button is clicked from the side panel.

Current event shape:

type ObjectActionEvent = {
  objectId: string;
  action: ObjectBindingAction;
  binding?: ObjectBinding;
  screenX?: number;
  screenY?: number;
};

onViewerReady

Optional callback fired once camera controls are available and again when the viewer publishes updated ready-state data (for example after model load, camera changes, or binding changes).

Current callback shape:

(viewer: ViewerReadyState) => void

ViewerReadyState includes captureImage, an imperative method for grabbing a PNG snapshot of the canvas:

type ViewerReadyState = {
  controls: CameraControls;
  scene: Object3D | null;
  objectBindings: Record<string, ObjectBinding>;
  nodeRefs: Record<string, Object3D>;
  captureImage: (options?: CaptureImageOptions) => Promise<string>;
};

type CaptureImageOptions = {
  width?: number;
  height?: number;
  transparent?: boolean;
};

captureImage forces a render and resolves with a data:image/png URL. Pass width/height to render at a resolution other than the canvas's current size, and transparent to hide the configured background so the PNG carries an alpha channel instead. It rejects if called before the viewer is ready.

onViewerReady={(viewer) => {
  viewer
    .captureImage({ width: 1920, height: 1080, transparent: true })
    .then((dataUrl) => {
      // upload, preview, etc.
    });
}}

Note: requesting a custom width/height briefly resizes the live canvas to render at that resolution before restoring it, which can cause a momentary flicker on screen — fine for an occasional snapshot, not for rapid/looped calls.

If you're also using useViewerCamera's handleViewerReady, call both from your own onViewerReady to get camera helpers and captureImage together:

onViewerReady={(viewer) => {
  handleViewerReady(viewer);
  captureImageRef.current = viewer.captureImage;
}}

onTextureUpload

Optional async callback for handling texture file uploads. When provided, the viewer calls it instead of creating a blob URL, letting consumers upload to their own storage (S3, Cloudinary, a CDN, etc.) and return a durable URL that survives page reloads.

Current callback shape:

(file: File, objectId: string) => Promise<string>;

The returned string is stored in binding.style.material.texture.path via onObjectBindingsChange.

If omitted, the viewer falls back to URL.createObjectURL(file) which produces a short blob URL that works for the current session but is lost on reload.

Example:

<ModelViewer
  modelUrl="/model.glb"
  licenseKey="your-license-key"
  objectBindings={objectBindings}
  onObjectBindingsChange={setObjectBindings}
  onTextureUpload={async (file, objectId) => {
    const formData = new FormData();
    formData.append("file", file);
    formData.append("objectId", objectId);
    const res = await fetch("/api/upload-texture", {
      method: "POST",
      body: formData,
    });
    const { url } = await res.json();
    return url; // e.g. "https://cdn.example.com/textures/abc123.png"
  }}
/>

onAnimationsReady

Optional callback fired after the GLB/GLTF model is loaded, providing animation controls. If the model contains no animations, it is still called with an empty clips array and no-op control functions.

Current callback shape:

(controls: AnimationControls) => void

Where AnimationControls is:

type AnimationPlaybackState = {
  currentClip: string | null;
  isPlaying: boolean;
  speed: number;
  time: number; // live position of the current clip, in seconds
  duration: number; // length of the current clip, in seconds
};

type AnimationControls = {
  clips: string[];
  clipDetails?: { sourceName: string; duration: number }[];
  play: (clipName: string) => void;
  pause: () => void;
  stop: () => void;
  setSpeed: (speed: number) => void;
  seek?: (time: number) => void; // scrub the current clip to an absolute time (seconds)
  getState?: () => AnimationPlaybackState;
  subscribe?: (listener: (state: AnimationPlaybackState) => void) => () => void;
};

Wire this to useViewerAnimations().handleAnimationsReady for the simplest integration. When sceneConfig.animations.autoplayClip is set, ModelViewer will auto-play that clip on load and respect per-clip loopMode, speed, displayName, and soft-delete (hidden) settings.

lights

Optional custom lighting to render inside the scene.

If omitted, ModelViewer uses the library's default light rig.

Example:

function CustomLights() {
  return (
    <>
      <ambientLight intensity={0.5} />
      <directionalLight position={[4, 8, 4]} intensity={1.6} castShadow />
      <pointLight position={[-3, 3, 2]} intensity={0.8} />
    </>
  );
}

<ModelViewer
  modelUrl="/model.glb"
  licenseKey="your-license-key"
  objectBindings={objectBindings}
  lights={<CustomLights />}
/>;

camera

Optional custom camera configuration passed through to the underlying React Three Fiber Canvas.

ModelViewer only sets a default fov: 50 — it does not set a default position, so an unset position falls back to React Three Fiber's own Canvas default ([0, 0, 5]). Pass an explicit position for predictable framing.

Example:

<ModelViewer
  modelUrl="/model.glb"
  licenseKey="your-license-key"
  objectBindings={objectBindings}
  camera={{
    position: [0, 2.2, 7],
    fov: 40,
    near: 0.1,
    far: 1000,
  }}
/>

backgroundColor

Optional background color for the viewer canvas.

Example:

<ModelViewer
  modelUrl="/model.glb"
  licenseKey="your-license-key"
  objectBindings={objectBindings}
  backgroundColor="#0f172a"
/>

shadows

Optional boolean that controls whether the viewer renders shadows.

Default:

true;

When true, the canvas renders soft shadows: the default light rig casts a shadow from a directional key light, furniture and decor meshes cast and receive shadows, and ambient occlusion is applied through post-processing. When false, shadow map rendering is disabled entirely on the canvas, so there is no shadow-pass cost (the per-mesh and light castShadow/receiveShadow flags are simply ignored).

Example:

<ModelViewer
  modelUrl="/model.glb"
  licenseKey="your-license-key"
  objectBindings={objectBindings}
  shadows={false}
/>

Interior models (rooms, dollhouses): a single large mesh usually forms the walls/ceiling enclosure. If that shell cast shadows it would seal the whole interior in darkness when lit from outside, so the viewer automatically detects the enclosure (a mesh spanning most of the scene footprint in both horizontal axes) and excludes it from casting while still letting it receive shadows. Furniture and decor then cast realistic contact shadows onto the floor. See How Rendering Works.

onCameraChange

Optional callback fired whenever the camera controls update the camera.

Current callback shape:

(camera: Camera, controls: CameraControls) => void

showObjectBindingDataPanel

Optional boolean that controls whether the built-in left object details panel is rendered.

Default:

true;

customObjectBindingDataPanel

Optional render prop for replacing the built-in left object details panel.

Current prop shape:

type CustomObjectBindingDataPanelProps = {
  isOpen: boolean;
  selectedObject: ObjectBinding | null;
  currentAction: ObjectActionEvent | null;
  onClose: () => void;
  onAction: (event: ObjectActionEvent) => void;
};

When provided, ModelViewer passes its existing internal handlers into your custom panel. Your panel can call them, wrap them, or ignore them.

customSceneObjectsPanel

Optional render prop for replacing the built-in right scene objects panel.

Current prop shape:

type CustomSceneObjectsPanelProps = {
  objectBindings: Record<string, ObjectBinding>;
  onAction?: (event: ObjectActionEvent) => void;
  onFocus?: (binding: ObjectBinding) => void;
  onHover?: (binding: ObjectBinding | null) => void;
};

When provided, ModelViewer passes the current bindings plus its built-in action, focus, and hover handlers into your custom panel.

showSceneObjectsPanel

Optional boolean that controls whether the built-in right scene objects panel is rendered.

Default:

true;

showDownloadButton

Optional boolean that enables the download split-button (export GLB / export PNG screenshot).

Default:

true;

The bottom-right action bar only renders at all when at least one of showResetButton, showDownloadButtons, or (showAnnotationNavigation with annotations present) is true. Within that bar, the download button itself requires both showDownloadButtons and showDownloadButton to be true.

downloadFilename

Optional filename stem for the built-in model export button.

Default:

"model";

showResetButton

Optional boolean that shows the "reset camera view" button in the bottom-right action bar.

Default:

true;

showDownloadButtons

Optional boolean — master toggle for the download split-button area in the bottom-right action bar. Set to false to hide it regardless of showDownloadButton.

Default:

true;

showMouseController

Optional boolean that renders an on-screen joystick controller for moving the camera with a mouse or touch — useful on touch devices or kiosk layouts where drag-to-orbit is awkward.

Default:

false;

mouseControllerPosition

Optional placement for the on-screen controller.

type MouseControllerPosition =
  | "bottom-left"
  | "bottom-right"
  | "top-left"
  | "top-right"
  | "center"
  | "center-bottom"
  | "center-top";

mouseControllerOpacity

Optional opacity for the on-screen controller.

Default:

1;

moveSensitivity

Optional movement sensitivity for the on-screen controller.

Default:

0.08;

zoomSensitivity

Optional zoom sensitivity for the underlying CameraControls zoom interaction (mouse wheel / trackpad / pinch).

Default:

1.0;

Example:

<ModelViewer
  modelUrl="/model.glb"
  licenseKey="your-license-key"
  objectBindings={objectBindings}
  showMouseController
  mouseControllerPosition="bottom-right"
  mouseControllerOpacity={0.8}
  moveSensitivity={0.1}
  zoomSensitivity={1.2}
/>

sceneConfig

Optional scene-wide configuration object (SceneConfig) covering model, camera, lighting, wireframe, shadows, environment, background, ground shadows, post-processing, animations, and annotations. It is the same shape authored by BindingBuilder's Scene tab. If omitted, the viewer uses its built-in default scene config.

sceneConfig.animations drives autoplay and per-clip playback settings, and sceneConfig.annotations seeds the annotation markers rendered on the model.

disableZoom

Optional boolean. When true, the viewer never zooms the camera to an object on selection (selection still highlights and fires callbacks).

Default:

false;

zoomOnSelected

Optional boolean controlling whether selecting an object zooms/fits the camera to it. Set to false to keep the current camera framing on selection. Zooming is also skipped when disableZoom is true.

Default:

true;

onAutoFit

Optional async callback fired once the model has loaded and the scene is ready. When provided, the viewer calls it so consumers can run their own fit-to-scene behavior (e.g. an animated fit); if omitted, the viewer falls back to its internal fitScene.

Current callback shape:

() => Promise<boolean>;

refitOnResize

Optional boolean controlling whether the camera re-frames the model to fit whenever the canvas is resized — a browser window resize, a device rotation, or a side panel opening/closing (which changes how much width the canvas has). Set to false to preserve the user's current orbit/zoom across resizes; the camera aspect stays correct either way, so the model never distorts, it just isn't re-centered. This only affects re-fits after the initial mount-time auto-fit.

Default:

true;

onAnnotationsChange

Optional callback fired when the annotation markers on the model change (added, edited, or removed through the viewer UI).

Current callback shape:

(annotations: AnnotationMarker[]) => void

Where AnnotationMarker is the SceneAnnotationMarker shape:

type AnnotationMarker = {
  id: number;
  worldPosition: [number, number, number];
  localPosition: [number, number, number];
  title: string;
  description: string;
};

activeAnnotation / onActiveAnnotationChange

Optional controlled state for which annotation is currently open. Pass activeAnnotation to control it from your app, and onActiveAnnotationChange to be notified when the viewer wants to open (AnnotationMarker) or close (null) one. If activeAnnotation is left undefined, the viewer manages this state internally (uncontrolled).

Current shapes:

activeAnnotation?: AnnotationMarker | null;
onActiveAnnotationChange?: (annotation: AnnotationMarker | null) => void;

renderMode

Optional render loop mode. "demand" (default) only re-renders the canvas when something changes (camera move, state update, animation frame); "always" runs a continuous render loop.

maxDpr

Optional upper bound for the device pixel ratio used when rendering, so retina/4K displays don't render at full 2–3x cost.

Default:

2;

performanceProfile

Optional control over how aggressively the viewer trades visual fidelity for a stable WebGL context on constrained GPUs.

performanceProfile?: "auto" | "high" | "low";

• "auto" (default) — applies a reduced profile on handheld/mobile browsers and other low-power touch devices: the postprocessing pipeline is skipped, soft shadows are disabled, and the device pixel ratio is capped. Desktop-class touch devices may still keep the higher-quality path when they advertise plenty of memory. This keeps mobile GPUs within their memory budget so the context isn't lost — which also keeps WebXR (enableXR) usable, since a lost context can't start a session.
• "high" — always render at full quality (postprocessing, soft shadows, full maxDpr), even on mobile. Use when you know the target devices can handle it.
• "low" — always apply the reduced profile, on any device.

Default:

"auto";

dracoDecoderPath / ktx2TranscoderPath / meshopt

Optional controls for the compressed-asset decoders used when loading the GLB/GLTF asset.

dracoDecoderPath?: string | false;
ktx2TranscoderPath?: string | false;
meshopt?: boolean;

DRACO, Meshopt, and KTX2 decoding are enabled by default via hosted decoder/transcoder bundles, fetched lazily only when the model needs them. Pass a path to self-host the decoder/transcoder files, or false to disable that decoder.

showMeasureTools

Optional boolean that shows a click-to-measure toolbar over the canvas: click two points on the model for a distance readout, plus a toggleable bounding-box dimensions overlay.

Default:

false;

measurementUnit

Optional unit suffix appended to measurement readouts. glTF models are authored in meters by spec, so values are not converted — this only changes the displayed label.

Default:

"m";

enableXR

Optional boolean that enables XR entry points. On WebXR-capable browsers, the viewer shows a "View in your space" (AR) and/or "Enter VR" button once navigator.xr.isSessionSupported(...) resolves true for that mode. On iPhone/iPad, WebXR AR is not available, but if you also pass usdzUrl, the viewer shows a "View in AR" button that launches Apple Quick Look instead.

On entering a session the model is normalized (scaled to ~1 m on its longest axis) and rested on the floor a short distance in front of the viewer, so large/real-scale scenes are framed instead of engulfing the viewer.

AR placement gestures — inside an AR session the viewer now uses an explicit placement flow:

• before placement, a bottom label says "Move your device over a flat surface" until a hit-testable surface is found
• once a surface is found, a reticle appears on it and the label changes to "Tap to place"
• tapping the screen or the label places the model at the reticle
• after placement, pinch (two fingers) resizes the model and twist rotates it around its vertical axis without changing its position
• a bottom "Relocate" button lets the user press-and-hold to bring the reticle back; releasing the button places the model at the current reticle position

VR sessions keep the initial framed placement (there are no real surfaces to hit-test against).

Postprocessing is automatically disabled during an XR session (the effect composer isn't WebXR-aware). Note also that on low-power devices the default performanceProfile of "auto" already disables postprocessing and soft shadows — important for keeping the WebGL context alive so AR can start at all.

Default:

false;

usdzUrl

Optional USDZ URL used as an Apple-device fallback when enableXR is true. On iPhone/iPad, if WebXR AR is unavailable and this prop is provided, the viewer shows a "View in AR" button that launches Apple Quick Look for the given asset.

usdzUrl?: string;

Notes:

• this should point to a .usdz file that Safari can fetch directly
• Android / WebXR-capable devices ignore this and continue using the normal WebXR AR flow
• if usdzUrl is omitted, Apple handheld devices simply won't get an AR button

showAnnotationNavigation

Optional boolean that shows the "Guided Tour" control cluster when the model has at least one annotation: a single "Guided Tour" button that, once started, becomes Previous/Stop/Next controls for stepping through annotations in order.

Default:

true;

Theming the scene objects / object binding panels

The scene objects panel and object binding data panel read their colors, borders, shadows, and fonts from CSS custom properties (--ri-sidepanel-* and --ri-databinding-*) instead of hardcoded values, each with the current look baked in as a fallback. Override them on a .ri-viewer ancestor to re-skin those panels:

.my-app .ri-viewer {
  --ri-sidepanel-bg: #1a0033;
  --ri-sidepanel-accent: #ff2d75;
}

See the full variable list in the ModelViewer docs.

SimpleModelViewer Public API

type SimpleModelViewerProps = {
  modelUrl: string;
  backgroundColor?: string;
  showSceneObjectsPanel?: boolean;
  showSceneSettingsPanel?: boolean;
  enableModelUpload?: boolean;
  zoomOnSelected?: boolean;
  highlightOnHover?: boolean;
  refitOnResize?: boolean;
  // Initial values for the scene settings (environment) panel
  backgroundEnabled?: boolean;
  autoRotate?: boolean;
  envPreset?: PresetsType; // @react-three/drei environment preset
  exposure?: number;
  ambientIntensity?: number;
  ambientColor?: string;
  directionalIntensity?: number;
  directionalColor?: string;
  onModelLoaded?: (scene: Object3D) => void;
  onLoadError?: (error: unknown) => void;
};

SimpleModelViewer does not take a licenseKey — licensing is enforced by ModelViewer and BindingBuilder only.

modelUrl

URL or public path to the .glb or .gltf model to inspect. For .gltf URLs with external .bin or texture files, those files must be hosted at the relative paths declared in the .gltf.

backgroundColor

Optional canvas background color.

Default:

"#1a1a1a";

showSceneObjectsPanel

Optional boolean that controls whether the right-side scene objects panel is rendered.

Default:

true;

showSceneSettingsPanel

Optional boolean that controls whether the left-side environment/scene settings panel is rendered. It exposes background color/visibility, the @react-three/drei environment preset, auto-rotate, exposure, and ambient/directional light color and intensity.

Default:

true;

Scene settings defaults

The following optional props seed the initial values of the scene settings (environment) panel. Each maps to one control, and the panel stays interactive so the user can still adjust them at runtime. They are initial values (not controlled props): changing one after mount does not override a value the user has since changed in the panel — the exception is backgroundColor, which stays in sync live.

| Prop | Type | Panel control | Default | | ---------------------- | ------------- | ----------------------- | ----------- | | backgroundEnabled | boolean | Background on/off | false | | autoRotate | boolean | Auto Rotate | false | | envPreset | PresetsType | Environment preset | "city" | | exposure | number | Exposure | 1 | | ambientIntensity | number | Ambient Light Intensity | 0.6 | | ambientColor | string | Ambient Light Color | "#ffffff" | | directionalIntensity | number | Direct Light Intensity | 1.2 | | directionalColor | string | Direct Light Color | "#ffffff" |

envPreset accepts any @react-three/drei PresetsType (for example "city", "sunset", "dawn", "night", "warehouse", "forest", "apartment", "studio", "park", "lobby").

<SimpleModelViewer
  modelUrl="/model.glb"
  backgroundEnabled
  envPreset="sunset"
  exposure={1.2}
  ambientIntensity={0.4}
  directionalColor="#fff4e0"
  autoRotate
/>

zoomOnSelected

Optional boolean. When true, selecting a mesh (via click or the objects panel) zooms/frames the camera on it.

Default:

false;

highlightOnHover

Optional boolean. When true, hovering a mesh (in the viewport or the objects panel) highlights it.

Default:

false;

refitOnResize

Optional boolean controlling whether the camera re-frames the model to fit whenever the canvas is resized — a browser window resize, a device rotation, or a side panel (scene settings / scene objects) opening or closing. Set to false to preserve the user's current orbit/zoom across resizes; the camera aspect stays correct either way, so the model never distorts, it just isn't re-centered.

Default:

true;

enableModelUpload

Optional boolean that swaps the fixed modelUrl workflow for a built-in upload UI. When enabled, the viewer starts with a drag-and-drop / file-picker empty state and loads the uploaded .glb, standalone/data-URI .gltf, or .zip containing a .gltf plus its referenced .bin and texture files instead of the asset passed via modelUrl.

Default:

false;

onModelLoaded

Optional callback fired after the GLB/GLTF scene has loaded.

onLoadError

Optional callback fired if the model fails to load or render.

Object Binding Shape

The current source defines these binding types internally:

type ObjectBindingAction = {
  id: string;
  label: string;
  type: "command";
};

type ObjectBindingCameraState = {
  position?: [number, number, number];
  target?: [number, number, number];
  fov?: number;
  zoom?: number;
};

type ObjectBindingMaterial = {
  // exported by the package; includes texture/baseColor plus the supported
  // MeshPhysicalMaterial overrides used by the viewer and BindingBuilder
};

type ObjectBindingStyle = {
  material?: ObjectBindingMaterial;
};

type ObjectBinding = {
  id: string;
  type: ObjectBindingType; // "body" | "light" | "wheel" | "glass" | "interior" | "floor" | "wall" | "door" | "furniture" | "decor" | "electronics" | "other" | ...
  modelObjectId: string;
  label?: string;
  visible?: boolean;
  selectable?: boolean;
  hoverable?: boolean;
  style?: ObjectBindingStyle;
  actions?: ObjectBindingAction[];
  metrics?: Record<string, number>;
  metadata?: Record<string, unknown>;
  cameraState?: ObjectBindingCameraState;
};

Notes:

• the objectBindings record is keyed by node name, not by id
• visible is live render state, not just an initial default
• style.material.baseColor is read by the renderer and is the committed source of truth for color picks
• style.material.texture.path is read by the renderer and is the committed source of truth for texture uploads (stored as durable URLs via onTextureUpload when provided, or session-scoped blob URLs otherwise)
• if no texture.path is provided and no style.material.baseColor is set, the viewer falls back to the node's original GLB/GLTF material
• supported style.material fields are applied as per-object MeshPhysicalMaterial overrides, including metalness, roughness, emissive, opacity, alpha masking, normal/bump, AO, displacement, clearcoat, sheen, anisotropy, specular, transmission, thickness, attenuation tint/distance, reflectivity, and side selection
• each style.material group also accepts a texture-map slot (metalnessMap, roughnessMap, normalMap, aoMap, clearcoatMap, etc.); color maps are decoded as sRGB and data maps as linear automatically
• BindingBuilder intentionally omits exact Sketchfab glossiness, cavity, and subsurface-scattering workflows; those require preprocessing or a different material pipeline
• cameraState stores a saved camera view for the object; when both position and target are set, the viewer uses that view when the object is focused or selected instead of falling back to fitToBox
• metrics and metadata are displayed in the side panel JSON preview
• ObjectBindingType is a large union covering vehicles, rooms, furniture, characters, weapons, environment, and more

Supported Built-In Actions

Action handling is currently hardcoded in ModelViewer.

Implemented behaviors

• toggle-visibility Hides or shows the selected mesh by setting binding.visible and calling onObjectBindingsChange
• change-color Opens the color picker; the chosen hex is applied as a live preview while dragging and committed into binding.style.material.baseColor via onObjectBindingsChange when the picker closes
• change-material Opens the texture upload popup for JPG, PNG, and WebP files; if onTextureUpload is provided, the file is passed to it and the returned URL is stored in binding.style.material.texture.path; otherwise a session-scoped blob URL is used as the fallback

How Rendering Works

At a high level, the current viewer does the following:

1. creates a Three.js canvas; only fov: 50 is defaulted, so camera position falls back to React Three Fiber's Canvas default ([0, 0, 5]) unless camera.position is passed
2. loads the GLB/GLTF asset with useGLTF
3. looks up meshes by the keys in objectBindings (resolving modelObjectId to find the actual model node)
4. clones each referenced material so edits stay isolated per object (keyed on a structural signature of the binding-to-mesh mapping, not the objectBindings reference, so materials are not recreated on every binding update)
5. applies runtime color, texture, and style overrides from objectBindings in a useEffect (not during render)
6. manages a reference-counted texture cache so the same texture URL is decoded once and disposed when no longer referenced; each texture is decoded in the correct color space — color maps (base color/albedo, emissive, sheen color, specular color) as sRGB and data maps (normal, roughness, metalness, AO, displacement, etc.) as linear — and the cache is keyed by URL and color space, so the same image can be reused safely as both a color and a data map
7. adds hover, selected, and panel-hover emissive highlighting
8. creates an AnimationMixer for the loaded scene, ticked every frame via useFrame, and exposes playback controls through onAnimationsReady
9. renders a side panel for the selected object and its configured actions

Only objects listed in objectBindings are rendered interactively by the current Model component.

Lighting, shadows, and post-processing

When shadows is enabled (the default), the canvas renders soft shadow maps and the viewer applies:

• a default light rig (Lights) with ambient + hemisphere fill and a directional key light that casts shadows, sized to the model
• per-mesh castShadow/receiveShadow, with one exception: the large enclosing "shell" mesh (walls/ceiling of an interior model) is detected by its bounding-box size and excluded from casting so a top-down light still reaches the interior — it continues to receive shadows, so furniture casts visible contact shadows onto the floor and walls
• a post-processing stack (EffectComposer) with SSAO ambient occlusion (normal pass enabled), bloom, vignette, and ACES filmic tone mapping

Pass shadows={false} to disable shadow rendering entirely, or pass a custom lights rig to replace the default lighting.

UI Behavior

The current component includes its own UI shell:

• a viewer layout that fills its parent container
• a sliding left side panel about 280px wide
• a canvas area that fills the remaining width
• a floating color picker popover
• a floating texture upload popover
• a right scene objects panel with search and per-object visibility toggles

Because of that, it works best when mounted in a container with an explicit height.

Usage Expectations For Models

To use this library successfully, your GLB/GLTF asset should follow these expectations:

• the mesh node names must match the keys in objectBindings (or be referenced via modelObjectId)
• target nodes should have geometry and a MeshStandardMaterial
• the file should be accessible from the browser at modelUrl; hosted .gltf files must also serve external .bin and texture files at their declared relative paths

If a node name or material name does not match, that object will not render through the interactive binding flow.

License

Proprietary — see LICENSE. Installing the package does not itself grant a right to use it in production; a valid licenseKey from the Developer Portal is required, and usage is bound to the terms of your license tier.