🚨 PROJECT STATUS: EXPERIMENTAL 🚨
This product is 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, without writing any code, on as many browsers and devices as possible.
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.
TODO: Project has not been published to npm so most of these examples do not yet actually work.
You can load a bundled build via unpkg.com:
<script src="https://unpkg.com/@google/model-viewer/dist/model-viewer-element.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 it is 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
<script src="path/to/bundled/model-viewer-element.js"></script>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-element.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> 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.
📢 Check out POLYFILLS.md to learn how to polyfill for maximum browser compatibility!
- ✅ No polyfill needed
- 🚧 Requires a polyfill
- 🚫 Not available
- 🎌 Available but unstable
| Feature | Chrome | Canary | Safari 12 | Firefox 63 | Firefox 62 | Edge | IE 11 |
|---|---|---|---|---|---|---|---|
| Resize Observer | ✅ | ✅ | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 |
| Custom Elements | ✅ | ✅ | ✅ | 🚧 | 🚧 | 🚧 | 🚧 |
| Shadow DOM | ✅ | ✅ | ✅ | ✅ | 🚧 | 🚧 | 🚧 |
| Intersection Observer | ✅ | ✅ | 🚧 | ✅ | ✅ | ✅ | 🚧 |
| Fullscreen API | 🚧 | ✅ | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 |
| Web XR Device API | 🚫 | 🎌 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 |
| Web XR HitTest API | 🚫 | 🎌 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 |
src: The URL to the 3D model. Note: only glTF/GLB files are supported. For more information, see the Supported Formats section.ios-src: The url to a USDZ model will be used in iOS Safari to launch Quick Look for AR.preload: Whether or not the user must select the element first before the model begins to download. Keep in mind models can be heavy on bandwidth and use preloading with caution.poster: Displays an image instead of the model until the model is loaded or a user action.controls: Enables controls via mouse/touch when in flat view.ar: Enables the option to enter AR and place the 3D model in the real world if the platform supports it. On iOS, this requires thatios-srchas also been configured.background-color: Sets the background color of the flat view. Takes any valid CSS color string.auto-rotate: Enables the auto rotation of the model.
All attributes have a corresponding property in camel-case format. For example,
the background-color attribute can also be configured using the
backgroundColor property.
'load': Fired when a model is loaded. Can fire multiple times per<model-viewer>if changing thesrcattribute.
A <model-viewer>'s attributes allows developers to specify multiple file types to
work across different platforms. For WebGL and Web XR 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 Web XR Device and Hit Test APIs.
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.
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 artifactsnpm 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.npm test- Runs tests.
Apache License Version 2.0, Copyright © 2018 Google