<model-viewer>is currently in the Experimentation phase. Someone on the team thinks it’s an idea worth exploring, but it may not go any further than this. Use at your own risk.
<model-viewer> is a web component that makes rendering interactive 3D
models - optionally in AR - easy to do, on as many browsers and devices as possible.
<model-viewer> strives to give you great defaults for rendering quality and
As new standards and APIs become available
<model-viewer> will be improved
to take advantage of them. If possible, fallbacks and polyfills will be
supported to provide a seamless development experience.
You can load a bundled build via unpkg.com:
Alternatively, you can install the npm package:
npm install ---save @google/model-viewer
Important note on bundling
Bundled builds are useful for demos or for kicking the tires. However, the bundled build includes some third party dependencies. Some of these dependencies (like three) are quite large. For production use cases we recommend that you use the npm package and your own bundler (such as Rollup or Webpack) to eliminate potential duplicate dependencies.
If you are using a bundled build, first add a script tag to your page to load it
Alternatively, if you are using the npm package and a bundler (see "Important note on bundling" above), you can import the module:
After the library has been loaded, a new custom element will be defined. You can use it anywhere you would write HTML. For example, using the bundled build in an HTML document might look like this:
<!doctype html> <html> <head> <title>3D Test</title> <script src="path/to/bundled/model-viewer.js"></script> </head> <body> <model-viewer src="path/to/model.gltf"></model-viewer> </body> </html>
import '@google/model-viewer'; const model = document.createElement('model-viewer'); model.src = 'path/to/model.gltf'; document.body.appendChild(model);
<model-viewer> builds upon standard web platform APIs so that the performance,
capabilities and compatibility of the library get better as the web evolves.
However, not all browsers support all of these features today. Below is the latest state of browser support for the relevant emerging features.
✅No polyfill needed 🚧Requires a polyfill 🚫Not available 🎌Behind a flag, unstable
|Feature||Chrome||Canary||Safari 12||Firefox 64||Firefox 62||Edge||IE 11|
|WebXR Device API|
|WebXR HitTest API|
1: Resize Observer is optional, and will be used if available. For more details please refer to POLYFILLS.md
IE 11 Support
We currently test and support Internet Explorer 11. We also distribute a special "legacy" bundle that is compatible with IE 11 but comes with the following important caveats:
- In order to use the "legacy" bundle in Chrome, you must also use the Custom Elements ES5 Adapter (see POLYFILLS.md for more detail on this).
Currently no custom CSS variables are supported, but the model viewer's containing box
can be sized via traditional
height properties, and positioned with
the typical properties (
Parameters that are required for display:
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.
Optional parameters (not required for display):
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.
auto-rotate: Enables the auto rotation of the model.
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
controls: Enables controls via mouse/touch when in flat view.
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
srcis 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.
posteris also enabled, the model will be downloaded before user action. See On Loading for more information.
preloadare specified, hide the poster and show the model once the model has been loaded. See On Loading for more information.
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.
All attributes have a corresponding property in camel-case format. For example,
background-color attribute can also be configured using the
'load': Fired when a model is loaded. Can fire multiple times per
srcattribute is changed.
preloadis enabled this event is fired when preloading is done.
<model-viewer>'s attributes allows developers to specify multiple file types to
work across different platforms. For WebGL and WebXR purposes, both
glTF and GLB are supported out of the box. Additionally,
developers can specify a USDZ file (using the
ios-src attribute) that
will be used to launch Quick Look on iOS Safari as an interim solution until
Safari has support for something like the WebXR Device and Hit Test APIs.
Models are often large, so especially on pages with large numbers of them it
may be desirable to load them after user action. Three parameters -
reveal-when-loaded - control the loading
Four configuration options are available:
- By default, the model will load with the page and will be displayed once it's loaded.
- With a
posterspecified, the model will not load or display until the user takes action (for instance, by clicking on the model element).
- With both
preloadset, the model will load with the page, but the poster image will be displayed until the user takes action.
- With all of
reveal-when-loadedset, the poster will be displayed until the model is loaded, at which time the poster will be hidden and the model displayed.
See the loading examples
Important note on data usage
iOS Quick Look only supports model files that use the USDZ format. This means that iOS users who see a live-rendered model in the browser (loaded as glTF/GLB) will have to download the same model a second time in USDZ format when they launch Quick Look.
There are currently multiple options for viewing content in augmented reality. Different platforms enable slightly different experiences, but generally finds a real-world surface and allows the user to place the model, to be viewed through a camera.
unstable-webxr enable AR features
on certain platforms -- read the API attributes for each to
understand the support and caveats.
When in augmented reality, all current platforms assume that the models unit size be in meters, such that a 1.5 unit tall model will be 1.5 meters when in AR.
See the augmented reality examples.
After you have cloned the repository locally, you should run:
This will install dependencies, run a build and run the tests. Build artifacts
are placed in the
The following npm scripts are available:
npm run clean- Deletes all build artifacts
npm run build- Builds the distributable from the
npm run watch- Watches the
src/directory, rebuilding when a file changes.
npm run serve- Serves a static server on port
8000from the project root.
npm run dev- Combination of
npm run watchand
npm run serve-- watches the
src/directory, rebuilding when a file changes and opens a static server on port
npm test- Runs tests.
This repo contains examples to demonstrate how <model-viewer> may be used. Before running them do the following:
cd path/to/cloned/repo npm install npm run build
To run the examples:
npm run serve
Apache License Version 2.0, Copyright © 2018 Google