Viewer (V2)

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 for more niche needs.

For instructions on integrating the Babylon Viewer into your project, see the NPM page.
For a smaller, WebGPU-only version of the Viewer, see Viewer Lite.
For details on the API, see the API docs.
For background on the goals and design principles of the Babylon Viewer, see the introduction blog post.
If you have any feedback or feature requests, see the announcement forum thread.
For details on the deprecated Babylon Viewer V1, see the legacy docs.

To get started, here is a very basic usage example:

See the Pen Babylon Viewer Basics by BabylonJS.

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:

npm install @babylonjs/viewer

See the NPM page for more details on using the NPM package.

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, 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).

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 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.

Dynamic Imports & Babylon Native

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.

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 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 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.

Viewer Configurator

The Viewer Configurator is a tool that simplifies configuring the Viewer. Find more details in the Viewer Configurator docs.

Viewer (V2)

Viewer Layers

File Formats

Engines

Power & Resource Optimizations

3D Commerce Certified

Viewer Configurator

Further reading

Loading Any File Type

Learn how to import any file type in Babylon.js.

Viewer Configurator

Learn about the Viewer Configurator, a tool to simplify configuring the Babylon Viewer.

WebGPU Snapshot Rendering

Learn how to use snapshot rendering for faster scene display

Coming next

Viewer Camera Controls

How to control the Viewer's camera.

Viewer HTML Element Interface

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

Viewer Lite

Using the smaller, WebGPU-only version of the Babylon Viewer.

Viewer Default UI

Default UI provided by the HTML3DElement (<babylon-viewer>).

Viewer HTML Element Styling

CSS styles, parts, and slots for the HTML3DElement (<babylon-viewer>).

Viewer HotSpots

HotSpots and annotations in the Viewer.

Viewer Advanced Usage

HotSpots and annotations in the Viewer.

Viewer & React

Using the Viewer with React.

Viewer Migration (V1 -> V2)

Migrating from the V1 Babylon Viewer to V2