# Viewer (V2)

> The viewer is the simplest way to display 3D content on a web page.

Source: https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer

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](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/advancedUsage) for more niche needs.

> [!NOTE]
> - 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](https://doc.babylonjs.com/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](https://doc.babylonjs.com/legacy/babylonViewer).

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

[CodePen: Babylon Viewer Basics](https://codepen.io/BabylonJS/pen/ogvbyyW/)

> [!WARNING]
> **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.

## 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](https://doc.babylonjs.com/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.

> [!WARNING]
> **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](https://github.com/BabylonJS/BabylonNative/blob/master/Documentation/ConsumingJavaScript.md#using-a-bundler-to-create-a-single-js-file).*

## 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](https://doc.babylonjs.com/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](https://doc.babylonjs.com/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](https://doc.babylonjs.com/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](https://doc.babylonjs.com/toolsAndResources/viewerConfigurator).

## Further reading

- [Viewer NPM](https://www.npmjs.com/package/@babylonjs/viewer)
- [Viewer API](https://doc.babylonjs.com/packages/viewer/index)
- [Viewer Blog Post](https://www.linkedin.com/pulse/babylon-viewer-v2-babylon-js-lkstc/?trackingId=8xWb1OZKqf5Rulor%2BbhCZQ%3D%3D)
- [Viewer Configurator Tool](https://viewerconfig.babylonjs.com)
- [Viewer Configurator Docs](https://doc.babylonjs.com/toolsAndResources/viewerConfigurator)
- [Babylon.js Supported Model Formats](https://doc.babylonjs.com/features/featuresDeepDive/importers/loadingFileTypes)
- [WebGPU Snapshot Rendering](https://doc.babylonjs.com/setup/support/webGPU/webGPUOptimization/webGPUSnapshotRendering)

## Pages in this section

- [Viewer Lite](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/viewerLite.md): Using the smaller, WebGPU-only version of the Babylon Viewer.
- [Viewer Camera Controls](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/cameraControls.md): How to control the Viewer's camera.
- [Viewer Default UI](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/defaultUI.md): Default UI provided by the HTML3DElement (<babylon-viewer>).
- [Viewer HTML Element Interface](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/elementInterface.md): Attributes and events of the HTML3DElement (<babylon-viewer>).
- [Viewer HTML Element Styling](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/elementStyling.md): CSS styles, parts, and slots for the HTML3DElement (<babylon-viewer>).
- [Viewer HotSpots](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/hotspots.md): HotSpots and annotations in the Viewer.
- [Viewer Advanced Usage](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/advancedUsage.md): HotSpots and annotations in the Viewer.
- [Viewer & React](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/react.md): Using the Viewer with React.
- [Viewer Migration (V1 -> V2)](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/migrationGuide.md): Migrating from the V1 Babylon Viewer to V2