model-viewer

Easily display interactive 3D models on the web & in AR

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.

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

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

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

Events

  • 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

Natively supported
Available with polyfill
Behind a flag, unstable
Not available

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

Feature Chrome Canary Safari 12 Firefox 65 Edge IE 11
Custom Elements
Shadow DOM

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

Feature Chrome Canary Safari 12 Firefox 65 Edge IE 11
Resize Observer
Intersection Observer

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

Feature Chrome Canary Safari 12 Firefox 65 Edge IE 11
Fullscreen API
WebXR Device API
WebXR HitTest API