<model-viewer>is currently in development. It's on the fast track to a 1.0 release, so we encourage you to use it and give us your feedback, but there are things that haven't been finalized yet and you can expect some changes.
<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
performance.
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.
Demo • Documentation • Kanban • Quality Tests
You can load a bundled build via UNPKG by including the snippet below. This will automatically load the correct version for the user's browser.
<!-- 💁 Include both scripts below to support all browsers! -->
<!-- Loads <model-viewer> for modern browsers: -->
<script type="module"
src="https://unpkg.com/@google/model-viewer/dist/model-viewer.js">
</script>
<!-- Loads <model-viewer> for old browsers like IE11: -->
<script nomodule
src="https://unpkg.com/@google/model-viewer/dist/model-viewer-legacy.js">
</script>Alternatively, you can install the npm package:
npm install ---save @google/model-viewer
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
<model-viewer> as described in the Installing section.
Alternatively, if you are using the npm package and a bundler (see "Important note on bundling" above), you can import the module:
import '@google/model-viewer';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>Alternatively, using the npm package in a JavaScript module might look like this:
import '@google/model-viewer';
const model = document.createElement('model-viewer');
model.src = 'path/to/model.gltf';
document.body.appendChild(model);You can think of <model-viewer> sort of like an <img> or <video> tag, but for
3D content. Just set its src attribute to the URL of a valid glTF (or
GLB) file and voila!
<model-viewer> is supported on the last 2 major versions of all evergreen
desktop and mobile browsers. <model-viewer> is also supported on IE11.
 Chrome |
 Firefox |
 Safari |
 Edge |
 IE11 |
|
|---|---|---|---|---|---|
| Desktop | ✅ | ✅ | ✅ | ✅ | ✅ |
| Mobile | ✅ | ✅ | ✅ | ✅ | N/A |
<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. Check out POLYFILLS.md to learn how to polyfill for maximum browser compatibility!
For full details regarding the attributes, properties, events and more supported
by <model-viewer>, please refer to our
online documentation.
Currently no custom CSS variables are supported, but the model viewer's containing box
can be sized via traditional width and height properties, and positioned with
the typical properties (display, position, etc.).
A <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 -
poster, preload, and reveal - control the loading
behavior.
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
posterandpreloadset, the model will load with the page, but the poster image will be displayed until the user takes action. - With all of
poster,preload, andreveal-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
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.
The attributes ar, ios-src, magic-leap and unstable-webxr enable AR
features on certain platforms. See the
documentation 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:
npm install
This will install dependencies, run a build and run the tests. Build artifacts
are placed in the lib and dist folders.
The following npm scripts are available:
npm run clean- Deletes all build artifacts.npm run build- Builds the distributable from thesrc/directory.npm run watch- Watches thesrc/directory, rebuilding when a file changes.npm run serve- Serves a static server on port8000from the project root.npm run dev- Combination ofnpm run watchandnpm run serve-- watches thesrc/directory, rebuilding when a file changes and opens a static server on port8000. Note: This does not rebuild everything, so if you made changes to tests or fidelity, you'll probably still need to run build separately to pick up the changes.npm test- Runs tests.npm run fetch-samples- Pull the Khronos sample models for fidelity testing. Note: This will download hundreds of megabytes of data the first time you run it.npm run check-fidelity- Compare rendering to third-party renderers.npm run update-screenshots- Take screenshots of fidelity tests using third-party renderers. If you get an error about not havingconvert, make sure to install Image Magick, e.g. on OSX runbrew install imagemagick.
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