model-viewer

Examples

• Animation

• Lazy Loading

• Model Formats

• Staging & Camera Control

• Lighting & Environment

• Augmented Reality

• Customizing UI

• Annotations

• Interactive Example

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 AR experiences on supported devices.

• ar-modes

  A prioritized list of the types of AR experiences to enable, if available; see Augmented Reality. Allowed values are "webxr", to launch the AR experience in the browser, "scene-viewer", to launch the Scene Viewer app, "quick-look", to launch the iOS Quick Look app, and "fallback", to launch a fullscreen non-AR experience in the event Scene Viewer fails to launch. You can specify any number of modes separated by whitespace. Defaults to "webxr scene-viewer quick-look fallback".

• ar-scale

  Controls the scaling behavior in AR mode in Scene Viewer. Set to "fixed" to disable scaling of the model, which sets it to always be at 100% scale. Defaults to "auto" which allows the model to be resized.

• auto-rotate

  Enables the auto-rotation of the model.

• auto-rotate-delay

  Sets the delay before auto-rotation begins. The format of the value is a number in milliseconds. The default is 3000.

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

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

• 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. Camera distance can also be set as a percentage ('%'), where 100% gives the model tight framing within any window based on all possible theta and phi values. Any time this value changes from its initially configured value, the camera will interpolate from its current position to the new value. Any value set to 'auto' will revert to the default.

  For camera-orbit, camera-target and field-of-view, parts of the property value can be configured with CSS-like functions. The CSS calc() function is supported for these values, as well as a specialized form of the env() function. You can use env(window-scroll-y) anywhere in the expression to get a number from 0-1 that corresponds to the current top-level scroll position of the current frame. For example, a value like "calc(30deg - env(window-scroll-y) * 60deg) 75deg 1.5m" cause the camera to orbit horizontally around the model as the user scrolls down the page.

  Defaults to "0deg 75deg 105%"

• camera-target

  Set the starting and/or subsequent point the camera orbits around. Accepts values of the form "$X $Y $Z", like "0m 1.5m -0.5m". Also supports units in centimeters ("cm") or millimeters ("mm"). A special value "auto" can be used, which sets the target to the center of the model's bounding box in that dimension. Any time this value changes from its initially configured value, the camera will interpolate from its current position to the new value. Defaults to "auto auto auto".

• environment-image

  Controls the environmental reflection of the model. Normally if skybox-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.

• 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 vertical field of view of the camera. Accepts values units in both degrees and radians (e.g., "30deg" or "0.5rad"). Accepts any value between 10 and 45 degrees. Any time this value changes from its initially configured value, the camera will interpolate from its current value to the new value. Defaults to "auto", which sets either the vertical or horizontal field of view to 45 degrees depending on the dimensions of the model and the aspect ratio of the canvas.

• 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", "when-focused" and "none". 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. The interaction prompt will only display if camera-controls are enabled. Defaults to "auto".

• interaction-prompt-style

  Configures the presentation style of the interaction-prompt when it is raised. The two allowed values are "wiggle" and "basic". When set to "wiggle", the prompt will animate from horizontally and the model will appear to be rotated as though the prompt is interacting with it. When set to "basic", the prompt is not animated, and instead simply appears until it is dismissed by user interaction. Defaults to "wiggle".

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

• max-camera-orbit

  Set the maximum orbital values of the camera. Takes values in the same form as camera-orbit, but does not support env(). Defaults to "Infinity 157.5deg Infinity". Note "Infinity" is not an accepted keyword, but the default can still be obtained by passing "auto".

• max-field-of-view

  Set the maximum field of view of the camera, corresponding to maximum zoom-out. Takes values in the same form as field-of-view, but does not support env(). Defaults to "45deg".

• min-camera-orbit

  Set the minimum orbital values of the camera, just like max-camera-orbit above. Defaults to "-Infinity 22.5deg 0".

• min-field-of-view

  Set the minimum field of view of the camera, corresponding to maximum zoom-in, just like max-field-of-view above. Defaults to "10deg".

• poster

  Displays an image instead of the model, useful for showing the user something before a model is loaded and ready to render. If you use a poster with transparency, you may also want to set --poster-color to transparent so that the background shows through. See our section on lazy loading for examples.

• loading

  An enumerable attribute describing under what conditions the model should be preloaded. The supported values are "auto", "lazy" and "eager". Auto is equivalent to lazy, which loads the model when it is near the viewport for reveal = "auto", and when interacted with for reveal = "interaction". Eager loads the model immediately. See our section on lazy loading for examples. Defaults to "auto".

• 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 when the model should be revealed. It currently supports three values: "auto", "interaction", and "manual". If reveal is set to "interaction", <model-viewer> will wait until the user interacts with the poster before loading and revealing the model. If set to "auto", the model will be revealed as soon as it is done loading and rendering. If set to "manual", the model will remain hidden until dismissPoster() is called. Defaults to "auto".

• shadow-intensity

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

• shadow-softness

  Controls the blurriness of the shadow. Set to 0 for hard shadows. Softness should not be changed every frame as it incurs a performance cost. Softer shadows render faster. Defaults to 1.

* Parameters that are required for display.

Note: All attributes have a corresponding property in camel-case format. For example, the skybox-image attribute can also be configured using the skyboxImage 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.

• ar-status

  This read-only attribute enables DOM content to be styled based on the status of the WebXR AR presentation. Possible values include 'not-presenting', 'session-started', and 'object-placed'. For instance, a prompt for the user to move their phone until the object is successfully placed in their space can be shown by scoping a CSS rule to model-viewer[ar-status="session-started"]. Setting this attribute has no effect.

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

• --min-hotspot-opacity

  Sets the opacity of hidden hotspots. Defaults to 0.25.

• --max-hotspot-opacity

  Sets the opacity of visible hotspots. Defaults to 1.

• --poster-color

  Sets the background-color of the poster. You may wish to set this to transparent if you are using a seamless poster with transparency (so that the background color of <model-viewer> shows through). 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.

• loaded

  This property is read-only. It returns true if the load event below has fired since the last src change.

• modelIsVisible

  This property is read-only. It returns true if the element is visible on the page (assuming there is an IntersectionObserver) and the poster has been dismissed.

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

  This static, writable property sets <model-viewer>'s DRACO decoder location URL. By default, the DRACO decoder will be loaded from a Google CDN.

• ModelViewer.minimumRenderScale

  This static, writable property sets <model-viewer>'s minimum rendering scale factor as it dynamically changes resolution to maintain framerate. Turn off this effect by setting to 1. Defaults to 0.5.

• 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. Default is 5.

Methods

• activateAR()

  Activates AR. Note that for any mode that is not WebXR-based, this method most likely has to be called synchronous from a user interaction handler. Otherwise, attempts to activate modes that require user interaction will most likely be ignored.

• dismissPoster()

  Dismisses the poster, causing the model to load and render if necessary. This is currently effectively the same as interacting with the poster via user input.

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

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

• getCameraTarget()

  Returns the realtime target position of the camera in meters. This value may differ from the value configured with the camera-target 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.

• positionAndNormalFromPoint(pixelX, pixelY)

  Returns the world position and normal of the point on the mesh corresponding to the input pixel coordinates given relative to the model-viewer element. The position and normal are returned as Vector3D, which has a method toString() that outputs a format suitable for putting in a hotspot's data-position and data-normal attributes. The function returns null if no object is hit.

• jumpCameraToGoal()

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

• ModelViewer.mapURLs(callback)

  If provided, the callback will be passed each resource URL before a request is sent. The callback may return the original URL, or a new URL to override loading behavior. This behavior can be used to load assets from .ZIP files, drag-and-drop APIs, and Data URIs. This is a static method.

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

• resetTurntableRotation()

  Resets the turntable that rotates the model when auto-rotate is enabled. The new value of the turntable rotation will be 0 after this method is invoked, but the model may not update until the next render frame.

• resetInteractionPrompt()

  Typically, the interaction prompt will only display once and then stops displaying after the user interacts with the 3D model for the first time. You can invoke this method in order to reset the interaction prompt after it has already been displayed. Doing so will cause it to display once again when the interaction-prompt display conditions have been met.

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

• toBlob(options: {mimeType, qualityArgument, idealAspect})

  Returns a promise that resolves into a Blob object in the format specified by the mimeType (defaults to image/png). A Blob object represents a file-like object of immutable, raw data. You can also specify a value between 0 and 1 for qualityArgument (Currently only available on Chrome desktop and Firefox) which defaults to 0.92 and 0.8 for image/png and image/webp respectively. By setting idealAspect to true, the blob will be captured at the ideal poster aspect ratio instead of the canvas aspect ratio. This allows for easy poster creation, where a single poster will match the render seamlessly at any canvas aspect ratio.

• updateHotspot({name, position, normal})

  Updates the position and/or normal of the hotspot associated with slot = name. The position and normal are given in the same string format as the hotspot attributes data-position and data-normal, which are also in the same format as the camera-target attribute.

Events

• ar-status

  Fired when the ar-status attribute above fires. The event.detail.status property will be set to the same value as the ar-status attribute, either 'not-presenting', 'session-started', or 'object-placed'. This event is only enabled for WebXR AR sessions.

• 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 skybox-image or environment-image, the image will have loaded by the time this event fires.

• error

  This event can be triggered for two reasons: a model has failed to load or parse, or the WebGL context was lost. If the model failed to load, event.detail.type will be 'loadfailure'. If the WebGL context was lost, event.detail.type will be 'webglcontextlost'. In both cases, recovery countermeasures are left as an exercise for the user. The element will not make automatic attempts to re-load a model that has failed to load. Nor will the element attempt to restore the GL context after it has been lost. Error events also hold a reference to the originating error event (when there is one) as event.detail.sourceEvent.

• 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, the element is in the viewport (assuming there is an IntersectionObserver), and the poster has been dismissed, this event will fire and event.detail.visible will be "true".

• 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 loading = "eager" 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 webxr in ar-modes:

Feature
WebXR Device API
WebXR HitTest API