Home

How to Use Model Viewer

Introduction

model-viewer is a javascript library by Google that makes it easy to add 3d content on a website. It uses custom HTML tags to do this so embedding a model is similar to adding an image or video to a webpage:

<model-viewer src="path/to/3dmodel.glb" alt="A 3D model"></model-viewer>

model-viewer takes care of framing the model on all screen sizes, i.e. it's responsive by default. Doing this with other 3d frameworks can often involve several lines of javascript code. It also allows for animated models, using environment images for lighting, annotations, camera controls, AR and more — a lot of which can be controlled directly through HTML parameters.

<model-viewer
	camera-controls
	skybox-image="path/to/skyboxImage.jpg"
	alt="A 3D model"
	src="path/to/3dmodel.glb">
</model-viewer>

Some useful links:

Device compatibility

The web standards for AR are still a work in progress, and constantly changing, as is browser support. model-viewer gets around this by using operating-system specific 'AR viewing apps' that integrate seamlessly with the browser experience. There are 3 modes available:

It's important to note that QuickLook and SceneViewer are native apps. Once AR mode is launched through these apps, any custom javascript code from the webpage will no longer be able to run. The functionality and UX are determined by the apps, and features such as annotations do not work in these modes.

Preparing a model

model-viewer accepts only .gltf or .glb models. (.gltf models often have textures stored as separate files. It's important to to keep them in the same relative location to the .gltf). For displaying a model in AR on iOS, one also needs to provide a .usdz version of the model.

Here are some tools that can help with converting a model to these formats :

Note on 3d model feature support:

QuickLook (on iOS devices) does not support all features part of the .gltf spec. When converting a model to .usdz, some of these features could be emulated, while some will not work at all. See here for a list of .usdz limitations from Sketchfab, and a more detailed list along with emulations possible through the Google command line tool.

Enabling AR

There are a few attributes that need to be included in the HTML tag for a model to work in AR:

<model-viewer
	src="path/to/3dmodel.glb"
	ios-src="path/to/USDZmodel.usdz"
	ar
	ar-mode="webxr scene-viewer quick-look"
	alt="A 3D model that works in AR">
</model-viewer>

See here for more examples. The object can also be placed on a wall instead of the floor, and the AR button can be customized. It's important to note that the AR button will only be displayed on devices that support AR, so while developing on a laptop/desktop this button will not appear.

If quick-look is specified in the ar-mode list, but no .usdz model is provided, one will be generated on the fly. This is a new feature however, and might not produce desired results.

Note about scale:

The only options for pre-setting scale (ar-scale) in AR mode are auto and fixed - auto allows the model to be resized by pinching, whereas fixed always renders the model at 100% scale. The gltf format's scale is set in meters — so a model of scale 1 will render fairly large in AR mode — keep this unit in mind while preparing the model.

Camera

model-viewer comes with default camera controls for rotation and zoom, the ability to set the camera orbit and target, auto-rotate, field of view and more. The camera works on a spherical coordinate system, set by a radius, and inclination and azimuth angles. Interact with this demo to see how these values affect the camera (+ play around with different lighting settings). See here for more examples and documentation.

Annotations

model-viewer lets you add annotations to the model by specifying its position and normal. Annotations can be styled through CSS, and can be set to be 'always visible' or occluded depending on the rotation of the model. Annotation ('hotspot') locations can be selected through the model-viewer editor (generates an HTML snippet and allows for entering label text), or on this page (displays position and normal values).

Here is how an annotation is plugged into the model-viewer HTML:

<model-viewer src="scene.glb" camera-controls>
    <button
			class="Hotspot"
			slot="hotspot-1"
			data-position="0.08125757912266225m 0.01903929367409709m 0.048820624535711885m"
			data-normal="-0.004757698885123861m 7.089523799901993e-11m -0.9999886820866116m"
			data-visibility-attribute="visible">
        <div class="HotspotAnnotation">Here is a label for the annotation</div>
    </button>
</model-viewer>

Note: Annotations currently work only in the browser and in WebXR mode for AR (Chrome 83+ on Android).

Using model-viewer with React / bundling tools

model-viewer might not always play well with frameworks like React and javascript bundling tools. Often a solution is to include the non-module version of model-viewer (or specify paths to both):

<script
	type="module"
  src="https://unpkg.com/@google/model-viewer/dist/model-viewer.min.js"
/>
<script
  nomodule
  src="https://unpkg.com/@google/model-viewer/dist/model-viewer-legacy.js"
/>

You can also use an import statement like so:

import "@google/model-viewer/dist/model-viewer-legacy"