
Viewer Lite is a smaller version of the Babylon Viewer powered by [`@babylonjs/lite`](https://www.npmjs.com/package/@babylonjs/lite). It provides the same `<babylon-viewer>` custom element and many of the same model-viewing capabilities as the full Viewer, but it is WebGPU-only and does not yet support every Viewer feature.

Use Viewer Lite when minimizing download size is important and its [current limitations](#current-limitations) are acceptable. Use the full Viewer when you need WebGL fallback, model formats other than glTF/GLB, or access to the full Babylon.js API.

## Enabling Viewer Lite

Viewer Lite is a separate package entry point, not a runtime option. Choose either the full Viewer or Viewer Lite for a page; do not import both because they register the same `<babylon-viewer>` custom element.

### NPM

Install the Viewer and Babylon Lite packages:

```bash
npm install @babylonjs/viewer @babylonjs/lite
```

Import the Lite entry point instead of `@babylonjs/viewer`:

```js
import "@babylonjs/viewer/lite";
```

Then use `<babylon-viewer>` as usual:

```html
<babylon-viewer source="https://playground.babylonjs.com/scenes/BoomBox.glb"></babylon-viewer>
```

The Lite entry point also exports `Viewer`, `CreateViewerForCanvas`, `HTML3DElement`, and `ConfigureCustomViewerElement` for programmatic use.

### CDN

To use Viewer Lite without a bundler, reference the Lite ESM bundle:

```html
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@babylonjs/viewer/dist/babylon-viewer-lite.esm.min.js"
></script>

<babylon-viewer source="https://playground.babylonjs.com/scenes/BoomBox.glb"></babylon-viewer>
```

If you self-host the bundle, deploy the complete `dist` directory so the entry point can load its relative chunks.

## Browser Support

Viewer Lite requires WebGPU and does not fall back to WebGL. Verify that WebGPU is available in every browser you support before choosing Viewer Lite.

## Current Limitations

The following Viewer features are not currently supported, or work differently, in Viewer Lite:

| Area | Viewer Lite limitation |
| --- | --- |
| Engines | WebGPU only. The `engine` attribute, WebGL, and full Viewer engine-creation options are not supported. |
| Model sources | Only string URLs are supported. `File` and `ArrayBufferView` sources are not supported. |
| Model formats | Only glTF and GLB are supported. The `extension`/`pluginExtension` options do not enable other loader formats. |
| Babylon.js API access | The full Viewer's `ViewerDetails` bridge is not available. Lite elements expose `viewer` instead of `viewerDetails`, but do not provide the full Viewer's public engine, scene, camera, model, and picking APIs. |
| SSAO | Not supported. Enabling `ssao` logs a warning and has no rendering effect. |
| Shadows | `none` and `normal` are supported; `high` is not. Set shadow quality before loading the model because changing it after loading does not rebuild the shadows. |
| Environments | `environment-intensity` has no rendering effect. After an environment or skybox is loaded, it cannot be replaced or removed without recreating the Viewer. An HDR environment cannot be used for lighting without also creating a skybox. |
| Embedded cameras | `camerasAsHotSpots` is not supported. Explicitly configured world and surface hotspots are supported. |
| Rendering suspension | `render-when-idle` and `autoSuspendRendering` are ignored. Rendering is still suspended when the Viewer is outside the browser viewport. |
| Loading options | `useOpenPBR`, `useRightHandedSystem`, and full Viewer loader options are not supported. |
| Loading progress | Loading progress is indeterminate; numeric byte progress is not reported. |
| Viewer Configurator | The Viewer Configurator currently targets the full Viewer. |




The Babylon Viewer uses Babylon's [`ArcRotateCamera`](/typedoc/classes/babylon.arcrotatecamera), so the camera interaction model centers on rotating the model around a target point or moving it closer to or farther from that target point. Additionally, there is custom behavior for changing the camera target and resetting the camera pose. In short:

| Mouse                      | Touch                    | Keyboard                        | Behavior                                                                                 |
| -------------------------- | ------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------- |
| Left click + drag          | One finger + drag        | Arrow keys                      | Rotate the camera around the target                                                      |
| Right click + drag         | Two fingers + drag       | Ctrl + Shift + arrow keys       | Pan the camera (move the target)                                                         |
| Wheel                      | Pinch                    | Alt/Option + up/down arrow keys | Zoom the camera                                                                          |
| Double click on model      | Double tap on model      | N/A                             | Raycast to set a new target (e.g. the camera will rotate around this point on the model) |
| Double click off the model | Double tap off the model | N/A                             | Reset the camera to its original pose                                                    |

Also note that any time the camera pose changes immediately (e.g. when resetting the camera pose, selecting a hotspot, or changing the target), the camera will smoothly interpolate to its new pose to avoid disorienting the user.



The Babylon Viewer aims to simplify a specific but common Babylon.js use case: loading, viewing, and interacting with a 3D model.

At the same time, the Babylon Viewer does ***not*** abstract away the Babylon.js API, but rather provides access to it. This ensures that you can leverage the common functionality of the Viewer but still bring your own [custom code/functionality](/features/featuresDeepDive/babylonViewer/advancedUsage) for more niche needs.

<Alert severity="info">
- For instructions on **integrating the Babylon Viewer** into your project, see the [NPM page](https://www.npmjs.com/package/@babylonjs/viewer).
- For a smaller, WebGPU-only version of the Viewer, see [Viewer Lite](/features/featuresDeepDive/babylonViewer/viewerLite).
- For **details on the API**, see the [API docs](https://doc.babylonjs.com/packages/viewer/index).
- For background on the **goals and design principles** of the Babylon Viewer, see the introduction [blog post](https://www.linkedin.com/pulse/babylon-viewer-v2-babylon-js-lkstc/?trackingId=8xWb1OZKqf5Rulor%2BbhCZQ%3D%3D).
- If you have any **feedback or feature requests**, see the [announcement forum thread](https://forum.babylonjs.com/t/babylon-viewer-v2/54317).
- For details on the deprecated Babylon Viewer V1, see the [legacy docs](/legacy/babylonViewer).
</Alert>

To get started, here is a very basic usage example:

<CodePen pen="ogvbyyW" tab="html,result" title="Babylon Viewer Basics" />

<Alert severity="warning" title="CDN vs. Bundler">
  In the example above (and all other Viewer examples in the docs), for simplicity the ESM bundle included in the NPM package is referenced through a public CDN.
  In most production scenarios, it is likely preferable to use the NPM packages directly with your own bundler and your own deployment. You can install the package into your project via:

  ```bash
  npm install @babylonjs/viewer
  ```

  See the [NPM page](https://www.npmjs.com/package/@babylonjs/viewer) for more details on using the NPM package.
</Alert>

## Viewer Layers

The Babylon Viewer is constructed in three layers to enable cross-platform and cross-framework usage.

**`HTML3DElement` (`<babylon-viewer>`)** - this layer leverages [HTML Custom Elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements), is intended for use directly in HTML, and provides default UI for things like animation controls. The documentation primarily focuses on this layer.

**`CreateViewerForCanvas`** - this layer binds Viewer functionality to an HTML `canvas`. It is used by `HTML3DElement`, and could be used for other web framework bindings (such as [React](https://react.dev/)).

**`Viewer`** - this layer has the bulk of the core Viewer functionality. It is used by `CreateViewerForCanvas`, and could be used in other Babylon scenarios, such as with Babylon Native.

## File Formats

The Babylon Viewer supports all formats supported by `@babylonjs/loaders`. See the [importer docs](/features/featuresDeepDive/importers/loadingFileTypes) for a complete list of supported formats.

Loaders are dynamically imported, so the user does not pay the download cost until the client loads a model format associated with the loader. Similarly, glTF extensions are dynamically imported and are not downloaded until a model is loaded that uses the extension.

<Alert title="Dynamic Imports & Babylon Native" severity="warning">
*When using Babylon Native, dynamic imports are not supported, so be sure to configure your bundler to create a single chunk. You can find more details in the [Babylon Native docs](https://github.com/BabylonJS/BabylonNative/blob/master/Documentation/ConsumingJavaScript.md#using-a-bundler-to-create-a-single-js-file).*
</Alert>

## Engines

`HTML3DElement` (`<babylon-viewer>`) and `CreateViewerForCanvas` support both WebGL and WebGPU. When not explicitly selected, the Viewer will default to an appropriate engine based on browser support and stability.

When WebGPU is used, [snapshot rendering](/setup/support/webGPU/webGPUOptimization/webGPUSnapshotRendering) is automatically enabled and managed. This can significantly improve performance for complex models.

For Babylon Native, a `NativeEngine` instance can be passed into the `Viewer` constructor.

The [Viewer Lite](/features/featuresDeepDive/babylonViewer/viewerLite) variant is WebGPU-only and does not provide a WebGL fallback.

## Power & Resource Optimizations

When a `HTML3DElement` (`<babylon-viewer>`) is not within the browser's viewport (e.g. scrolled out of view), rendering is suspended. Additionally, within the lower `Viewer` layer, when nothing is changing from frame to frame (e.g. no user interactions, no animations playing, etc.), rendering is also suspended. Suspending rendering is especially helpful on power- or resource-constrained devices (e.g. mobile), or when many Viewer instances are used on a page.

By default, `Viewer` will try to render at the native device resolution (maximum quality). When the `Viewer` is not able to render at the target framerate, the render resolution will progressively be reduced until the target frame rate is achieved, or the minimum resolution is reached.

## 3D Commerce Certified

The Babylon Viewer is configured by default to be compliant with the [Khronos 3D Commerce Certification](/setup/support/3D_commerce_certif).

## Viewer Configurator

The [Viewer Configurator](https://viewerconfig.babylonjs.com) is a tool that simplifies configuring the Viewer. Find more details in the [Viewer Configurator docs](/toolsAndResources/viewerConfigurator).


Viewer Lite

Enabling Viewer Lite

NPM

CDN

Browser Support

Current Limitations

Further reading

Viewer HTML Element Interface

Attributes and events of the HTML3DElement (<babylon-viewer>).

Area	Viewer Lite limitation
Engines	WebGPU only. The `engine` attribute, WebGL, and full Viewer engine-creation options are not supported.
Model sources	Only string URLs are supported. `File` and `ArrayBufferView` sources are not supported.
Model formats	Only glTF and GLB are supported. The `extension`/`pluginExtension` options do not enable other loader formats.
Babylon.js API access	The full Viewer's `ViewerDetails` bridge is not available. Lite elements expose `viewer` instead of `viewerDetails`, but do not provide the full Viewer's public engine, scene, camera, model, and picking APIs.
SSAO	Not supported. Enabling `ssao` logs a warning and has no rendering effect.
Shadows	`none` and `normal` are supported; `high` is not. Set shadow quality before loading the model because changing it after loading does not rebuild the shadows.
Environments	`environment-intensity` has no rendering effect. After an environment or skybox is loaded, it cannot be replaced or removed without recreating the Viewer. An HDR environment cannot be used for lighting without also creating a skybox.
Embedded cameras	`camerasAsHotSpots` is not supported. Explicitly configured world and surface hotspots are supported.
Rendering suspension	`render-when-idle` and `autoSuspendRendering` are ignored. Rendering is still suspended when the Viewer is outside the browser viewport.
Loading options	`useOpenPBR`, `useRightHandedSystem`, and full Viewer loader options are not supported.
Loading progress	Loading progress is indeterminate; numeric byte progress is not reported.
Viewer Configurator	The Viewer Configurator currently targets the full Viewer.