@google/model-viewer
Advanced tools
@google/model-viewer is a web component that allows you to easily display and interact with 3D models on the web. It supports various features such as AR (Augmented Reality) viewing, lighting controls, and animation.
Basic 3D Model Display
This feature allows you to display a 3D model with basic controls such as auto-rotation and camera controls.
<model-viewer src="path/to/your/model.glb" alt="A 3D model" auto-rotate camera-controls></model-viewer>Augmented Reality (AR) Support
This feature enables AR support, allowing users to view the 3D model in augmented reality using various AR modes.
<model-viewer src="path/to/your/model.glb" alt="A 3D model" ar ar-modes="webxr scene-viewer quick-look" camera-controls></model-viewer>Lighting and Environment
This feature allows you to add realistic lighting and environment settings to your 3D model, enhancing its visual appearance.
<model-viewer src="path/to/your/model.glb" alt="A 3D model" environment-image="path/to/your/environment.hdr" exposure="1" shadow-intensity="1" camera-controls></model-viewer>Animations
This feature supports animations within the 3D model, allowing you to play specific animations automatically.
<model-viewer src="path/to/your/model.glb" alt="A 3D model" animation-name="Run" autoplay camera-controls></model-viewer>Three.js is a popular JavaScript library for creating 3D graphics in the browser. It offers more flexibility and control over 3D rendering compared to @google/model-viewer but requires more setup and coding.
A-Frame is a web framework for building virtual reality (VR) experiences. It is more focused on VR and immersive experiences compared to @google/model-viewer, which is more geared towards easy 3D model viewing and AR.
Babylon.js is a powerful, open-source 3D engine that allows you to create complex 3D scenes and games. It offers more advanced features and capabilities compared to @google/model-viewer but also comes with a steeper learning curve.
🚨 Status: Experimental
<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>
<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.
See: API, Demo, Examples, Kanban (for work prioritization and progress)
You can load a bundled build via unpkg.com:
<script src="https://unpkg.com/@google/model-viewer/dist/model-viewer.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.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.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!
| Feature | Chrome | Canary | Safari 12 | Firefox 63 | Firefox 62 | Edge | IE 11 |
|---|---|---|---|---|---|---|---|
| Resize Observer | ✅ | ✅ | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 |
| Custom Elements | ✅ | ✅ | ✅ | 🚧 | 🚧 | 🚧 | 🚧 |
| Shadow DOM | ✅ | ✅ | ✅ | ✅ | 🚧 | 🚧 | 🚧 |
| Intersection Observer | ✅ | ✅ | 🚧 | ✅ | ✅ | ✅ | 🚧 |
| Fullscreen API | 🚧 | ✅ | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 |
| WebXR Device API | 🚫 | 🎌 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 |
| WebXR HitTest API | 🚫 | 🎌 | 🚫 | 🚫 | 🚫 | 🚫 | 🚫 |
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.).
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):
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 background-image supercedes background-color.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 src is
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.preload: When poster is also enabled, the model will be downloaded
before user action.
See On Loading for more information.reveal-when-loaded: When poster and preload are 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,
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 the src attribute is changed.'preload': When preload is enabled this event is fired when
preloading is done.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-when-loaded - control the loading
behavior.
Four configuration options are available:
poster specified, the model will not load or display until the
user takes action (for instance, by clicking on the model element).poster and preload set, the model will load with the page, but
the poster image will be displayed until the user takes action.poster, preload, and reveal-when-loaded set, 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 ios-src, magic-leap and 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:
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 the src/ directory.npm run watch - Watches the src/ directory, rebuilding when a file changes.npm run serve - Serves a static server on port 8000 from the project root.npm run dev - Combination of npm run watch and npm run serve -- watches the src/ directory, rebuilding when a file changes and opens a static server on port 8000.npm test - Runs tests.Apache License Version 2.0, Copyright © 2018 Google
FAQs
Easily display interactive 3D models on the web and in AR!
The npm package @google/model-viewer receives a total of 96,837 weekly downloads. As such, @google/model-viewer popularity was classified as popular.
We found that @google/model-viewer demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Newly introduced telemetry in devenv 1.4 sparked a backlash over privacy concerns, leading to the removal of its AI-powered feature after strong community pushback.
Security News
TC39 met in Seattle and advanced 9 JavaScript proposals, including three to Stage 4, introducing new features and enhancements for a future ECMAScript release.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.