<!-- Generated from reference/simple-model-viewer.mdx; edit the MDX source. -->

Package: @liveroom-tech/react-immersive
Canonical: https://react-immersive.liveroom.dev/docs/reference/simple-model-viewer

# `SimpleModelViewer`

A lightweight viewer for cases where you want to load a GLB, GLTF, OBJ, FBX, USDZ, STL, or PLY asset, inspect meshes, and toggle visibility **without** building `objectBindings`. It can either load a fixed `modelUrl` or, when `enableModelUpload` is enabled, let the user drag-and-drop or choose a local model at runtime.

## Usage

```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>
  );
}
```

## Behavior

- Discovers renderable meshes directly from the loaded model 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 color/intensity), each seedable via props
- Can swap `modelUrl` for a built-in drag-and-drop / file-picker upload flow
- Lets users click a mesh or panel row to select and focus it. Panel rows are buttons, so the keyboard can select from the panel too
- Fits the full scene on initial load, with space around it scaled to the model (`fitPadding`), and re-fits when the canvas is resized (window resize, device rotation, or a panel opening/closing). Set `refitOnResize={false}` to instead preserve the user's orbit/zoom
- Uses built-in ambient, directional, and environment lighting
- Renders on demand: frames are only drawn when something changes (camera movement, hover, auto-rotate, panel edits), so an idle viewer costs no GPU time or battery
- Degrades gracefully on very large models (above roughly 12 million triangles): viewport click/hover picking is disabled for performance, a dismissible banner explains this to the user, and selection stays available through the scene objects panel

  Use `SimpleModelViewer` when you want a quick inspection viewer. Use
  [`ModelViewer`](https://react-immersive.liveroom.dev/docs/reference/model-viewer) when you need binding-driven
  styling, actions, metadata, custom panels, exports, or animation integrations.

## Props

```ts
type SimpleModelViewerProps = {
  "aria-label"?: string; // default: localized "3D model viewer"
  "aria-labelledby"?: string; // ID(s) of naming text; takes precedence
  modelUrl: string;
  poster?: string;
  loading?: "lazy" | "eager"; // default "lazy"
  reveal?: "auto" | "interaction"; // default "auto"
  labels?: ModelViewerLabels;
  modelFormat?: "glb" | "gltf" | "obj" | "fbx" | "usdz" | "stl" | "ply";
  dracoDecoderPath?: string | false;
  ktx2TranscoderPath?: string | false;
  meshopt?: boolean;
  backgroundColor?: string;
  showSceneObjectsPanel?: boolean;
  showSceneSettingsPanel?: boolean;
  enableModelUpload?: boolean;
  zoomOnSelected?: boolean;
  highlightOnHover?: boolean;
  showLoadingOverlay?: boolean;
  refitOnResize?: boolean;
  cameraLimits?: CameraLimits;
  showResetButton?: boolean; // default true
  fitPadding?: number; // default 0.1, a fraction of the model's largest dimension
  zoom?: boolean; // default true
  pageScroll?: boolean; // default false
  showLoadError?: boolean; // default true
  reducedMotion?: "user" | "always" | "never";
  // Initial values for the scene settings (environment) panel
  backgroundEnabled?: boolean;
  autoRotate?: boolean;
  envPreset?: EnvironmentPreset; // default "neutral", built in
  environmentUrl?: string; // self-hosted HDR; overrides envPreset
  environmentEnabled?: boolean; // default true; false skips environment loading
  exposure?: number;
  ambientIntensity?: number;
  ambientColor?: string;
  directionalIntensity?: number;
  directionalColor?: string;
  envIntensity?: number;
  envRotation?: number;
  backgroundBlur?: number;
  toneMapping?: "aces" | "agx" | "neutral" | "none";
  groundShadow?: boolean;
  groundShadowOpacity?: number;
  showFloorGrid?: boolean;
  wireframe?: boolean;
  autoRotateSpeed?: number;
  fov?: number;
  onModelLoaded?: (model: ViewerModelInfo) => void;
  onLoadError?: (error: unknown) => void;
};
```


  `SimpleModelViewer` does not take a `licenseKey` or perform runtime key
  validation. It needs no key or paid plan, including for production use.
  See [Licensing](https://react-immersive.liveroom.dev/docs/licensing) for the component/environment matrix.

---

### `labels`

Optional plain-text overrides for built-in viewer text, including button titles, accessible labels, loading messages, tool hints, and AR placement controls. Missing keys retain their English defaults.

`ModelViewer` and `SimpleModelViewer` share the same dictionary. Each viewer has its own labels, and changing the prop updates text without reloading its model. See the [full label catalog](https://react-immersive.liveroom.dev/docs/reference/labels) for every key, default, and named placeholder.

`labels` does not translate annotation content, object metadata, custom panels, or raw server/loader diagnostics. Supply translations for those in your application.

```tsx
<SimpleModelViewer
  modelUrl="/car.glb"
  labels={{
    guidedTour: "Visite guidée",
    tapToPlace: "Touchez pour placer",
    sceneSettings: "Réglages",
    objectCount: "Objets : {count}",
  }}
/>
```

---

### `modelUrl`

**Required.** URL or public path to a `.glb`, `.gltf`, `.obj`, `.fbx`, `.usdz`, `.stl`, or `.ply` model. Hosted assets must serve external dependencies at their declared relative paths; USDZ dependencies are packaged internally.

---

### `modelFormat`

Optional explicit format for extensionless or signed URLs. Supported extensions are detected automatically in normal URLs.

---

### `poster` / `loading` / `reveal`

Work as on [`ModelViewer`](https://react-immersive.liveroom.dev/docs/reference/model-viewer#lazy-loading-and-posters),
sharing the same page-wide count of live 3D views. When a `SimpleModelViewer`
is put away, only its canvas goes: the panels and their settings stay, and the
canvas comes back with its camera, hidden objects and selection.
`onModelLoaded` runs again when it does.

---

### `dracoDecoderPath` / `ktx2TranscoderPath` / `meshopt`

Compressed-asset decoder configuration. Meshopt is bundled; DRACO and KTX2
default to immutable, versioned files on the first-party React Immersive domain.
Override with self-hosted directories or pass `false` to disable either format.
See the [`ModelViewer` decoder setup](https://react-immersive.liveroom.dev/docs/reference/model-viewer#dracodecoderpath--ktx2transcoderpath--meshopt).

---

### `backgroundColor`

Optional canvas background color.

Default:

```ts
"#1a1a1a";
```

---

### `showSceneObjectsPanel`

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

Default:

```ts
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:

```ts
true;
```

---

### Scene settings defaults

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

| Prop                   | Type          | Panel control           | Default     |
| ---------------------- | ------------- | ----------------------- | ----------- |
| `backgroundEnabled`    | `boolean`     | Show as background      | `false`     |
| `autoRotate`           | `boolean`     | Auto Rotate             | `false`     |
| `envPreset`            | `EnvironmentPreset` | Environment preset | `"neutral"` |
| `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"` |
| `envIntensity`         | `number`      | Environment Intensity   | `1`         |
| `envRotation`          | `number`      | Environment Rotation    | `0`         |
| `backgroundBlur`       | `number`      | Background Blur         | `0`         |
| `toneMapping`          | `"aces" \| "agx" \| "neutral" \| "none"` | Tone Mapping | `"aces"` |
| `groundShadow`         | `boolean`     | Ground Shadow           | `false`     |
| `groundShadowOpacity`  | `number`      | Shadow Opacity          | `0.5`       |
| `showFloorGrid`        | `boolean`     | Floor Grid              | `false`     |
| `wireframe`            | `boolean`     | Wireframe               | `false`     |
| `autoRotateSpeed`      | `number`      | Rotation Speed          | `1`         |
| `fov`                  | `number`      | Field of View           | `45`        |

The panel also lists the model's objects, triangles, materials and size, and **Reset Settings** returns every control to these starting values.

`envPreset` defaults to `"neutral"`, a studio light built into the package that
downloads nothing. The other presets (`"apartment"`, `"city"`, `"dawn"`,
`"forest"`, `"lobby"`, `"night"`, `"park"`, `"studio"`, `"sunset"`,
`"warehouse"`) are HDR files that `@react-three/drei` downloads from a public
CDN (`raw.githack.com`) when one is chosen, here or in the settings panel.

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

```ts
false;
```

---

### `highlightOnHover`

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

On very large models (above roughly 12 million triangles) viewport hover is disabled for performance regardless of this prop, panel-row hover highlighting still works.

Default:

```ts
false;
```

---

### `showLoadingOverlay`

Optional boolean controlling whether the built-in loading overlay is shown while the model is loading, uploaded files are being prepared, and the initial camera fit is settling.

The overlay takes `backgroundColor`, with a light card on a light background,
and leaves a `poster` visible underneath.

Default:

```ts
true;
```

---

### `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:

```ts
true;
```

---

### `reducedMotion`

Cuts motion the viewer starts on its own. `"user"` follows the visitor's device setting (`prefers-reduced-motion`); `"always"` and `"never"` override it. When motion is reduced, the `autoRotate` prop doesn't start auto-rotate (the visitor can still turn it on in the scene settings panel), camera moves jump instead of gliding, and panels appear in place. See [`ModelViewer`'s `reducedMotion`](https://react-immersive.liveroom.dev/docs/reference/model-viewer#reducedmotion).

Default:

```ts
"user";
```

---

### `enableModelUpload`

Optional boolean that swaps the fixed `modelUrl` workflow for a built-in upload UI. It accepts `.glb`, standalone/data-URI `.gltf`, `.obj`, `.fbx`, `.usdz`, `.stl`, `.ply`, or `.zip`. A ZIP may bundle GLTF dependencies, OBJ + MTL/textures, or FBX external textures; USDZ is already self-contained.

ZIP uploads are limited to 128 MiB compressed, 1,024 entries, 128 MiB per
expanded entry, 256 MiB expanded in total, and a 200:1 per-entry compression
ratio. Zipped GLTF assets may use `data:` URIs or paths included in the archive;
external asset URLs are rejected.

Default:

```ts
false;
```

---

### `onModelLoaded`

Optional callback fired after the model scene has loaded.

```ts
onModelLoaded?: (model: ViewerModelInfo) => void // { bounds, objectCount, materialVariants, materialVariantGroups }
```

---

### `onLoadError`

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

```ts
onLoadError?: (error: unknown) => void
```


### Self-hosted or disabled environment lighting

The default `"neutral"` lighting is generated in the browser, so a viewer makes
no lighting request unless you choose a downloadable preset. Set
`environmentUrl="/lighting/studio.hdr"` to use an HDR from your own origin
instead. The preset selector is hidden while a custom URL
is supplied. Use `environmentEnabled={false}` to make no environment-map request;
ambient and directional lights continue to work. Environment failures are isolated
from model loading, so an unavailable lighting asset does not remove the model.
Serve cross-origin environments with appropriate CORS headers.

### Camera limits and reset

`cameraLimits` accepts the same scene-unit distances, degree-based angles and
pan boundary as ModelViewer. Without distance overrides, the zoom range is 5%
to 10 times the model bounding-box diagonal. A camera reset button is shown by
default in the bottom-right corner after fitting; it restores the original
viewing direction and fits the current viewport. Set `showResetButton={false}`
to hide it.

### Framing: `fitPadding`

The viewer frames the model with space around it on each side, as a fraction
of the model's largest dimension: `0.1` (the default) leaves a tenth of it, so
a 30 cm product and a 10 m room fill the view alike. Use `0` for the tightest
fit, or a larger value for more room. While the model auto-rotates, the
framing also allows for its spin, so no part leaves the view as it turns.

### Zoom and page scrolling: `zoom` / `pageScroll`

`zoom={false}` turns off wheel, pinch and middle-drag zoom; dragging still
rotates and pans. The mouse wheel then scrolls the page.

`pageScroll` is for a viewer inside a scrolling page, such as a landing-page
hero. The mouse wheel scrolls the page, and holding Ctrl or ⌘ zooms (a
trackpad pinch still zooms). On touch screens a vertical swipe scrolls the
page, a sideways drag rotates the model, and two fingers zoom and pan.

### Landing-page embed

A spinning product that sits in a page, without the inspection interface:

```tsx
<div style={{ height: "60vh" }}>
  <SimpleModelViewer
    modelUrl="/product.glb"
    poster="/product-poster.jpg"
    backgroundColor="#f4f1ec"
    showSceneObjectsPanel={false}
    showSceneSettingsPanel={false}
    showResetButton={false}
    autoRotate
    groundShadow
    pageScroll
  />
</div>
```

- The three `show…={false}` props remove the side panels and the reset button.
- `pageScroll` keeps the wheel and vertical swipes scrolling the page.
- `poster` shows a picture of the model until its 3D view is drawn; the
  loading progress appears over it.
- The default lighting is built in, so the page makes no third-party
  requests. On a light `backgroundColor` the loading card is light too.
- Auto-rotate stops for visitors who ask for reduced motion.

### Accessible names

The viewer is a named region, including when both panels are disabled. Its default
name is "3D model viewer"; translate it with `labels.modelViewer`. Prefer a name
that describes the model on pages with several viewers:

```tsx
<SimpleModelViewer modelUrl="/chair.glb" aria-label="Chair preview" />

<h2 id="chair-heading">Chair preview</h2>
<SimpleModelViewer modelUrl="/chair.glb" aria-labelledby="chair-heading" />
```

`aria-labelledby` takes precedence over `aria-label` when its IDs reference naming
text. The region preserves access to its child controls. Collapsed panel buttons
have localized names and reference their panels through `aria-controls`.
Translate `openSceneSettingsPanel`, `closeSceneSettingsPanel`,
`openSceneObjectsPanel`, and `closeSceneObjectsPanel` through `labels` as needed.

### Failed model loads

A failed download or invalid file displays an accessible error with a retry
button. Retrying clears the failed loader cache entry and attempts the same URL
again. `onLoadError` still reports the underlying error for application logging.
The message names the cause, such as a missing file (404), an HTML page served
at the model URL, or a network failure. It remains visible when
`showLoadingOverlay={false}`; that prop controls loading progress only. Set
`showLoadError={false}` when you show your own error from `onLoadError`.
Override the `retryModelLoad` label for translated text.
