model-viewer

Examples

• Animation

• Lazy Loading

• Model Formats

• Staging & Camera Control

• Lighting & Environment

• Augmented Reality

Attributes

• src*

  The URL to the 3D model. This parameter is required for <model-viewer> to display. Only glTF/GLB models are supported, see Supported Formats.

• alt

  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.

• animation-name

  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.

• animation-crossfade-duration

  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.

• ar

  Enable the ability to launch Scene Viewer on supported devices.

• auto-rotate

  Enables the auto rotation of the model.

• autoplay

  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.

• background-color

  Sets the background color of the scene when viewed inline. Takes any valid CSS color string.

• background-image

  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.

• camera-controls

  Enables controls via mouse/touch when in flat view.

• camera-orbit

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

• environment-image

  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.

• environment-intensity

  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.

• experimental-pmrem

  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.

• field-of-view

  Used to configure the field of view of the camera. Accepts values units in both degrees and radians (e.g., "30deg" or "0.5rad"). Accepts any value between 20 and 45 degrees. Defaults to "45deg".

• interaction-prompt

  Allows you to change the conditions under which the visual and audible interaction prompt will display. Allowed values are "auto" and "when-focused". If set to "auto", the interaction prompt will be displayed as soon as the interaction-prompt-threshold (see below) time has elapsed (after the model is revealed). If set to "when-focused", the interaction prompt will only be activated if the element has first received focus. Defaults to "when-focused".

• interaction-prompt-threshold

  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.

• ios-src

  The url to a USDZ model which will be used on supported iOS 12+ devices via AR Quick Look on Safari. See Augmented Reality.

• magic-leap

  Enables the ability to view models in AR when viewing content on Magic Leap's Helio browser, requires that src is a GLB model, and requires the inclusion of the @magicleap/prismatic library.

• poster

  Displays an image instead of the model. See On Loading for more information.

• preload

  When poster is also enabled, the model will be downloaded before user action. See On Loading for more information.

• quick-look-browsers

  Set this attribute to control which iOS browsers will be allowed to launch AR Quick Look on iOS. Allowed values are "safari" and "chrome". You can specify any number of browsers separated by whitespace, for example: "safari chrome". Defaults to "safari".

• reveal

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

• shadow-intensity

  Controls the opacity of the shadow. Set to 0 to turn off the shadow entirely. Defaults to 0.

• stage-light-intensity

  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.

• unstable-webxr

  Enables the ability to view the model in AR via the experimental WebXR Device API, currently implemented only in Chrome Canary. See Augmented Reality.

* 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

• --poster-color

  Sets the background-color of the poster. Falls back to --background-color if set. Defaults to #fff.

• --poster-image

  Sets the background-image of the poster. This is currently overridden by the poster attribute if it is set. Defaults to none.

• --progress-bar-color

  Sets the background-color of the progress bar. Defaults to rgba(0, 0, 0, 0.4).

• --progress-bar-height

  Sets the height of the progress bar. Defaults to 5px.

• --progress-mask

  Sets the background of the progress mask. Defaults to #fff.

Properties

• currentTime

  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.

• paused

  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.

Methods

• getCameraOrbit()

  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.

• getFieldOfView()

  Returns the realtime camera vertical field of view in degrees. This value may differ from the value configured with the field-of-view attribute on account of user interaction or camera interpolation.

• jumpCameraToGoal()

  Changes the camera to its last configured goal state immediately on the next update instead of interpolating the motion over time.

• play()

  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.

• pause()

  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.

• toDataURL(type, encoderOptions)

  Returns a screenshot of the current model render in the format specified by type (defaults to image/png). The screenshot is encoded as a data URL string. In formats that support a sliding scale of quality (such as image/jpeg and image/webp) you can also specify a value for encoderOptions between 0 and 1 (encoderOptions defaults to 0.92 otherwise).

Events

• camera-change

  Fired when the camera position and/or field of view have changed. If the change occurred due to user interaction, the "event.detail.source" property will be set to "user-interaction".

• environment-change

  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.

• load

  Fired when a model is loaded. Can fire multiple times per <model-viewer> if the src attribute is changed.

• poster-visibility

  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

• play

  Dispatched when animations begin to play.

• pause

  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.

• preload

  When preload is enabled this event is fired when preloading is done.

Browser Support

These browser features are required for <model-viewer> to work correctly:

Feature
Custom Elements
Shadow DOM

These browser features are optional and are only used if available for performance optimization or specific features:

Feature
Resize Observer
Intersection Observer
Fullscreen API
:focus-visible

These browser features are optional and are only needed if you wish to use the unstable-webxr feature:

Feature
WebXR Device API
WebXR HitTest API