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. Defaults to false.

  • 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. Supports png, jpg and hdr (recommended) images. 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.

  • exposure

    Controls the exposure of both the model and skybox, for use primarily with HDR environments. Defaults to 1.

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

    Allows you to change whether the viewer requires focus before interacting with it. If set to "allow-when-focused", the user must focus on the viewer (click / tap) before being able to control it. If set to "always-allow", the user can control it even if the viewer is not the focused element on the page. Defaults to "always-allow".

  • 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. Defaults to 0.

  • 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

  • --ar-button-display

    Sets the display property of the AR button. Intended to be used to force the button to be hidden. Defaults to block.

  • --interaction-prompt-display

    Sets the display property of the interaction prompt. Intended to be used to force the prompt to be hidden. Defaults to flex.

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

  • ModelViewer.modelCacheSize

    This static, writable property sets <model-viewer>'s internal glTF model cache size, controlling number of individual models that should be cached. Note that any number of models may be cached at a given time. This number just sets the maximum number of models that can be cached even if they are not being used by a <model-viewer> element in the document. Note also that the cache size is measured in number of glTF models, not bytes! This is important to keep in mind, since any two models may have wildly different byte sizes.

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.

  • model-visibility

    This event is fired when the visibility of the model changes. When the model is loaded, able to be rendered and fully visible (e.g., the poster is no longer visible), this event will fire and event.detail.visible will be "true". Note that this event will fire regardless of whether the model is present in the viewport. This means that the model may not be rendered yet (as we do not render models that are outside of the viewport) even though the event says that the model is visible.

  • 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 or specific features:

Feature Chrome Canary Safari 12 Firefox 65 Edge IE 11
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 Chrome Canary Safari 12 Firefox 65 Edge IE 11
WebXR Device API
WebXR HitTest API
©Copyright 2018 Google Inc. Licensed under the Apache License 2.0.
Github ∙ Glitch ∙ Bug report