# Viewer HTML Element Interface

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

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

The `HTML3DElement` (`<babylon-viewer>`) custom element has a number of attributes and events that are not captured in the API documentation but are summarized below.

> [!NOTE]
> This page describes the full Viewer interface. Viewer Lite supports many of the same attributes and events, with the exceptions listed in the [Viewer Lite limitations](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/viewerLite#current-limitations).

## Attributes

> [!NOTE]
> Note that explicitly specified attribute values are re-applied when a new model is loaded.

| Attribute                 | Description                                                                                                                                                                                                                                                                                                                                          | Options                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `engine`                  | Which Babylon.js engine to use. Changing this value fully reloads the element.                                                                                                                                                                                                                                                                       | **`auto`**, `WebGL`, `WebGPU`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `render-when-idle`        | Indicates that the render loop should run unconditionally. By default, the render loop will be suspended when the visual output does not change from frame to frame. This can significantly reduce the energy demand on battery-constrained devices.                                                                                                 | Present or absent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `clear-color`             | The color that fills the element before each frame is rendered.                                                                                                                                                                                                                                                                                      | Any valid CSS color string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `source`                  | A URL referencing the model source.                                                                                                                                                                                                                                                                                                                  | Any valid URL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `extension`               | Explicitly specifies the file extension (format) of the `source`. Use this attribute if the format cannot be determined from the URL or the MIME type.                                                                                                                                                                                               | Any extension supported by any [importer](https://doc.babylonjs.com/features/featuresDeepDive/importers/loadingFileTypes)                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `environment`             | A URL referencing an [environment](https://doc.babylonjs.com/features/featuresDeepDive/materials/using/HDREnvironment). The environment is used for both image-based lighting (IBL) and the skybox. This is effectively a shorthand for setting `environment-lighting` and `environment-skybox` to the same texture. Set to `auto` to explicitly use the default environment. | Any valid URL, `auto`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `environment-lighting`    | A URL referencing an [environment](https://doc.babylonjs.com/features/featuresDeepDive/materials/using/HDREnvironment). The environment is used for image-based lighting (IBL) only. If no environment is provided and a model with PBR materials is loaded, a default environment will automatically be used. Set to `auto` to explicitly use the default environment.      | Any valid URL, `auto`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `environment-skybox`      | A URL referencing an [environment](https://doc.babylonjs.com/features/featuresDeepDive/materials/using/HDREnvironment). The environment is used for the skybox only. Set to `auto` to explicitly use the default environment.                                                                                                                                                 | Any valid URL, `auto`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `environment-rotation`    | The environment rotation in radians.                                                                                                                                                                                                                                                                                                                 | Numeric value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `environment-intensity`   | The environment lighting intensity.                                                                                                                                                                                                                                                                                                                  | Numeric value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `environment-visible`     | If the environment (skybox) should be visible.                                                                                                                                                                                                                                                                                                       | Present or absent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `skybox-blur`             | How much to blur the skybox.                                                                                                                                                                                                                                                                                                                         | Numeric value between 0 and 1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `shadow-quality`          | The quality of the shadows rendered (higher quality has higher performance overhead).                                                                                                                                                                                                                                                                | **`none`**, `normal`, `high`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `tone-mapping`            | The tone mapping mode.                                                                                                                                                                                                                                                                                                                               | **`neutral`**, `standard`, `aces`, `none`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `contrast`                | The contrast applied to the scene.                                                                                                                                                                                                                                                                                                                   | Any numeric value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `exposure`                | The exposure applied to the scene.                                                                                                                                                                                                                                                                                                                   | Any numeric value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `ssao`                    | Indicates whether Screen Space Ambient Occlusion (SSAO) is enabled in the scene. The SSAO effect is applied by default if the loaded model has no materials.                                                                                                                                                                                         | **`auto`**, `enabled`, `disabled`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `camera-auto-orbit`       | Indicates the camera should automatically orbit its target when the scene is otherwise idle.                                                                                                                                                                                                                                                         | Present or absent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `camera-auto-orbit-speed` | How fast to orbit the camera when `camera-auto-orbit` is enabled.                                                                                                                                                                                                                                                                                    | Any numeric value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `camera-auto-orbit-delay` | The delay in milliseconds before auto orbit takes effect when the scene becomes idle.                                                                                                                                                                                                                                                                | Any non-negative numeric value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `camera-orbit`            | Overrides the default camera orbit, defined by alpha (longitudinal rotation), beta (latitudinal rotation), and radius (distance from target).                                                                                                                                                                                                        | Three values separated by white space (alpha beta radius). Each value can either be `auto` or a numeric value (rotation in radians). For example: `3.14 auto 5`                                                                                                                                                                                                                                                                                                                                                     |
| `camera-target`           | Overrides the default camera target, defined by an `x y z` world-space coordinate.                                                                                                                                                                                                                                                                   | Three values separated by white space (x y z). Each value can either be `auto` or a numeric value (distance in world space). For example: `auto 2 auto`                                                                                                                                                                                                                                                                                                                                                             |
| `selected-animation`      | The default animation that is selected when the model is loaded.                                                                                                                                                                                                                                                                                     | A numeric value that is the index of the animation                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `animation-speed`         | The default animation speed.                                                                                                                                                                                                                                                                                                                         | `0.5`, **`1`**, `1.5`, `2`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `animation-auto-play`     | Indicates the default animation should automatically start playing when the model is loaded.                                                                                                                                                                                                                                                         | Present or absent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `material-variant`        | The default material variant to select when the model is loaded.                                                                                                                                                                                                                                                                                     | The name of the material variant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `hotspots`                | Defines all hotspot data. See the [hotspots](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/hotspots) docs for more details.                                                                                                                                                                                                                               | A JSON string matching the hotspots schema                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `cameras-as-hotspots`     | Indicates cameras loaded with models should be converted to hotspots and automatically added to `hotspots`.                                                                                                                                                                                                                                          | Present or absent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `reset-mode`              | Defines the behavior of the reset button.                                                                                                                                                                                                                                                                                                            | **`auto`**, `reframe`, or a space separated list of `source`, `environment`, `camera`, `animation`, `post-processing`, `material-variant`. `auto` restores the initial camera pose taking into account `camera-orbit` and `camera-target`, unless other viewer state might result in the model being out of view, in which case a full reframe is performed. `reframe` reframes the camera, ignoring `camera-orbit` and `camera-target`. The other values are used to reset the corresponding aspect of the viewer. |

## Events

| Event                            | Description                                                                                                                               |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `modelchange`                    | Fired when the model changes (loaded or cleared).                                                                                         |
| `modelerror`                     | Fired when a model fails to load.                                                                                                         |
| `loadingprogresschange`          | Fired when the progress state changes while loading a model.                                                                              |
| `environmentchange`              | Fired when the environment changes (loaded or cleared).                                                                                   |
| `environmentconfigurationchange` | Fired when the environment configuration changes (rotation, intensity, blur, etc.).                                                       |
| `environmenterror`               | Fired when an environment fails to load.                                                                                                  |
| `shadowsconfigurationchange`     | Fired when the shadows configuration changes (quality, etc.).                                                                             |
| `selectedanimationchange`        | Fired when the selected animation changes.                                                                                                |
| `animationspeedchange`           | Fired when the animation speed changes.                                                                                                   |
| `animationplayingchange`         | Fired when animation begins playing or is paused.                                                                                         |
| `animationprogresschange`        | Fired when the elapsed time on the animation timeline changes.                                                                            |
| `selectedmaterialvariantchange`  | Fired when the selected material variant changes.                                                                                         |
| `viewerready`                    | Fired when the underlying viewer instance has finished async initialization. This happens any time the element is reconnected to the DOM. |
| `viewerrender`                   | Fired every time the scene is rendered. This can be used for advanced scenarios like custom screen space hotspot UI.                      |

## Examples

Explicitly specifying the initial **camera pose** for a splat (which can be difficult to auto frame):

[CodePen: Babylon Viewer Camera Pose](https://codepen.io/BabylonJS/pen/dPbGqaY/)

Enabling and customizing **camera auto orbit**:

[CodePen: Babylon Viewer Camera Auto Orbit](https://codepen.io/BabylonJS/pen/QwLNyxq/)

## Further reading

- [Viewer HTML Element Styling](https://doc.babylonjs.com/features/featuresDeepDive/babylonViewer/elementStyling)
- [Viewer API](https://doc.babylonjs.com/packages/viewer/index)