Swap Model Variants

This demonstrates the use of the glTF materials variants extension which allows multiple materials and textures to be packed with a single geometry in a GLB. Our API exposes these variant names as availableVariants and you can select one using the variantName attribute. This is similar functionality to the lower-level scene-graph API below, but in that case it is up to you to choose the right texture URL, rather than having that information stored in the GLB. Note: setting variantName to null reverts to the initial material.

Model Transformations

This demonstrates the orientation and scale attributes which allow the model to be transformed. Note that if specified before the model loads, they will be taken into account by the automatic camera framing. If they are changed afterwards the camera will not move, so to get new automatic framing the updateFraming() method must be called.

Note that these changes can be made in AR as well, but only in WebXR mode, as this is the only mode that remains in the browser. Changes you made ahead of time will not be reflected in Scene Viewer, since this app downloads the original model again from its URL. iOS Quick Look will reflect your changes as long as ios-src is not specified, since in this case a USDZ will be generated on the fly from the current state.

Tip: When building custom interactive overlay controls with text or numeric input fields on mobile, ensure your inputs are styled with a CSS rule setting font-size: 16px; (or larger). If a focused text field's computed font size is below 16px, mobile WebKit browsers (like iOS Safari and Chrome) will automatically zoom in the entire viewport, which does not automatically reset when the input is blurred and can break the page layout.

AR Keyboard Overlays: Inside a WebXR full-screen immersive AR session, mobile browsers do not shrink the layout viewport when a software virtual keyboard is open. To prevent inputs from being covered by the keyboard, you can register a visualViewport resize listener (only active when ar-status="session-started") to calculate the soft keyboard's overlay height and dynamically translate your overlay container upward (e.g., via transform: translateY(-offset px);), as demonstrated in the script below.

Change Material Base Color

Note that color factors can be set two ways: [r, g, b, a] or a CSS-style color string. For array input, the values are between 0 and 1 and represent a linear color space, identical to the glTF spec. For string inputs, the values are internally converted from the sRGB color space, so this is likely more user-friendly.

As above, you can change these values in AR, but only in WebXR mode. iOS Quick Look does not reflect these color changes as USDZ does not appear to support colors multiplied onto textures.

Change Material Metalness and Roughness Factors

As above, you can change these values in AR, but only in WebXR mode. iOS Quick Look does reflect these property changes since they are not also textured.

Create textures

As above, you can change these values in AR, but only in WebXR mode. iOS Quick Look reflects these texture changes so long as the USDZ is auto-generated.

Swap textures

As above, you can change these values in AR, but only in WebXR mode. iOS Quick Look reflects these texture changes so long as the USDZ is auto-generated.

Transform textures

As above, you can change these values in AR, but only in WebXR mode. iOS Quick Look reflects these texture changes so long as the USDZ is auto-generated.

Toggle between Mesh Variants

If you have a few mesh variants, you can hide and show them by changing textures opacity.

Create animated textures

Though video textures are not part of the glTF spec yet, you can create them and add them to your model after it loads. Video elements, Canvas elements, and Lottie animations are all supported.

For Lottie animations, an import map is required, pointing "three" to the model-viewer library file you are loading, since three.js is contained in the model-viewer bundle. Unfortunately this cannot be done by our library automatically because the import map must be specified before any libraries load. Put something like this in your page's head:

<script type="importmap">
{
  "imports": {
    "three": "path/to/your/model-viewer.min.js"
  }
}
</script>
            

Unfortunately, Safari does not yet support import maps, so to get this to work universally, you will need the following code instead:

<script async src="https://ga.jspm.io/npm:es-module-shims@1.6.3/dist/es-module-shims.js"></script>

<script type="importmap-shim">
{
  "imports": {
    "three": "path/to/your/model-viewer.min.js"
  }
}
</script>

<script type="module-shim" src="path/to/your/model-viewer.min.js"></script>
            

Materials API

The complete Materials interface is documented below, which is all accessible through the model property. The Materials API is designed to follow the glTF structure, just as though you are navigating their JSON object. Only the materials and their children are exposed rather than the whole scene graph to keep the scope small for this high-level web component. Not every glTF parameter is exposed, but more may be added in the future. Additionally, several methods have been added for useful operations.

This example demonstrates selecting a material with pointer input and changing its color. Note this also works in the WebXR AR mode. It also demonstrates the use of the scale attribute since this GLB was erroneously modeled in mm instead of meters.

Exporter