Viewer HTML Element Interface

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.

Attributes

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
environment	A URL referencing an environment. 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. 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. 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 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):

Enabling and customizing camera auto orbit:

Further reading

• Viewer API