Easily display interactive 3D models on the web & in AR
Configures the model with custom text that will be used to describe the model to viewers who use a screen reader or otherwise depend on additional semantic context to understand what they are viewing.
Selects an animation to play by name. This animation will play when the .play() method is invoked, or when the <model-viewer> is configured to autoplay. If no animation-name is specified, <model-viewer> always picks the first animation it finds in the model.
When the current animation is changed, <model-viewer> automatically crossfades between the previous and next animations. This attribute controls how long the crossfade is in milliseconds. Defaults to 300.
Enable the ability to launch Scene Viewer on supported devices.
Enables the auto rotation of the model.
If this is true and a model has animations, an animation will automatically begin to play when this attribute is set (or when the property is set to true). If no animation-name is specified, plays the first animation.
Sets the background color of the scene when viewed inline. Takes any valid CSS color string.
Sets the background image of the scene when viewed inline. Takes a URL to an equirectangular projection image that's used for the skybox, as well as applied as an environment map on the model. Currently only supports traditional image formats (png, jpg), and does not yet support HDR (#65). Setting background-image supercedes background-color.
Enables controls via mouse/touch when in flat view.
Set the starting and/or subsequent orbital position of the camera. You can control the azimuthal and polar angles, and the distance from the model. Accepts values of the form "$angle $angle $distance", like "10deg 75deg 1.5m". Also supports units in radians ("rad") for angles and centimeters ("cm") or millimeters ("mm") for camera distance. A special value "auto" can be used for the distance, which sets the distance to the ideal framing distance based on the responsive scaling applied to the model scene. Any time this value changes from its initially configured value, the camera will interpolate from its current position to the new value. Defaults to "0deg 75deg auto".
Controls the environmental reflection of the model. Normally if background-image is set, that image will also be used for the environment-image. Use environment-image to only set the reflection without affecting the background.
Controls the intensity of environmental lighting. There is almost always light reflected from the environment, even when background-image or environment-image are not set. The one exception is for models with unlit materials. Set this value to 0 to hide the environment entirely. Defaults to 1.
Enables an experimental lighting mode that is more physically realistic, and emphasizes light from the environment over light from the built-in scene lights. Refer to this article for in-depth details related to this lighting mode.
When camera-controls are enabled, <model-viewer> will prompt the user visually (and audibly, for screen readers) to interact if they focus it but don't interact with it for some time. This attribute allows you to set how long <model-viewer> should wait (in milliseconds) before prompting to interact. Defaults to 3000.
Displays an image instead of the model. See On Loading for more information.
When poster is also enabled, the model will be downloaded before user action. See On Loading for more information.
This attribute controls whether or not the model should be automatically revealed when loaded. It currently supports two values: "auto" and "interaction". If reveal is set to "interaction", <model-viewer> will wait until the user interacts with the poster before loading and revealing the model. Otherwise, the model will be revealed as soon as it is done loading and rendering. Defaults to "auto".
Controls the opacity of the shadow. Set to 0 to turn off the shadow entirely. Defaults to 0.
Controls the intensity of the built-in scene lighting. Set to 0 to turn off the scene lighting entirely. Note that the weight of the scene lighting is effected by whether or not PMREM is enabled. Defaults to 1.
* Parameters that are required for display.
Note: All attributes have a corresponding property in camel-case format. For example, the background-color attribute can also be configured using the backgroundColor property.
CSS Custom Properties
Sets the background-color of the poster. Falls back to --background-color if set. Defaults to #fff.
Sets the background-image of the poster. This is currently overridden by the poster attribute if it is set. Defaults to none.
Sets the background-color of the progress bar. Defaults to rgba(0, 0, 0, 0.4).
Sets the background of the progress mask. Defaults to #fff.
This property reports the current track time of the currently selected animation. If no animations are available, the value is always 0. This property can be set in order to seek along the timeline of the currently playing animation. For example, if you set it to 0, it will reset an animation to the beginning.
This property is read-only. It returns true if animations are paused. It returns false if animations are playing. Animations always start paused, and remain so unless the autoplay attribute is set or the .play() method is invoked.
Returns the realtime orbital position of the camera. Azimuthal (theta) and polar (phi) angles are representred as radians, and the distance (radius) is represented in meters. This value may differ from the value configured with the camera-orbit attribute on account of user interaction or camera interpolation.
Causes animations to be played. Use the autoplay attribute if you want animations to be played automatically. If there are no animations, nothing will happen, so make sure that the model is loaded before invoking this method.
Causes animations to be paused. If you want to reset the current animation to the beginning, you should also set the currentTime property to 0.
Fired when the environment has changed. If the environment is derived from background-image or environment-image, the image will have loaded by the time this event fires.
Fired when a model is loaded. Can fire multiple times per <model-viewer> if the src attribute is changed.
This event is fired when the visiblity of the poster image changes. The current visibility state can be read from the event.detail.visible property
Dispatched when animations begin to play.
Dispatched when animations are paused. A model always begins in the paused state, so it is worth mentioning that this event will not be dispatched until the the pause() method is invoked after animations have begun playing.
When preload is enabled this event is fired when preloading is done.
These browser features are required for <model-viewer> to work correctly:
These browser features are optional and are only used if available for performance optimization:
These browser features are optional and are only needed if you wish to use the unstable-webxr feature:
|WebXR Device API|
|WebXR HitTest API|