model viewer safari

@google/model-viewer

• 2 Dependencies
• 92 Dependents
• 66 Versions

<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.

Demo • Documentation • Quality Tests

The <model-viewer> web component can be installed from NPM :

It can also be used directly from various free CDNs such as jsDelivr and Google's own hosted libraries :

For more detailed usage documentation and live examples, please visit our docs at modelviewer.dev !

Important note about versions

Our goal for <model-viewer> is to be a consistent, stable part of your web platform while continuing to deliver cutting-edge features. We’ll always try to minimize breaking changes, and to keep the component backwards compatible. See our guide to contributing for more information on backwards compatibility.

For your production site you may want the extra stability that comes by pinning to a specific version, and upgrading on your own schedule (after testing).

If you’ve installed via NPM , you’re all set - you’ll only upgrade when you run npm update . Note that three.js is a peer dependency, so that must also be installed, but can be shared with other bundled code. Note that <model-viewer> requires the version of three.js we test on to maintain quality, due to frequent upstream breaking changes. We strongly recommend you keep your three.js version locked to <model-viewer> 's. If you must use a different version, npm will give you an error which you can work around using their --legacy-peer-deps option, which will allow you to go outside of our version range. Please do not file issues if you use this option.

Browser Support

<model-viewer> is supported on the last 2 major versions of all evergreen desktop and mobile browsers.

<model-viewer> builds upon standard web platform APIs so that the performance, capabilities and compatibility of the library get better as the web evolves.

Development

To get started, follow the instructions in the main README.md file .

The following commands are available when developing <model-viewer> :

• webaronarcore
• webaronarkit
• augmented reality
• model-viewer

Package Sidebar

npm i @google/model-viewer

Git github.com/google/model-viewer

github.com/google/model-viewer#readme

Downloads Weekly Downloads

Unpacked size, total files, last publish.

2 months ago

Collaborators

Augmented Reality

This demonstrates several augmented reality modes, including webxr , scene-viewer , quick-look , & the accompanying attributes, magic-leap , ios-src , quick-look-browsers ., ar attributes.

Enable the ability to launch AR experiences on supported devices.

Controls the scaling behavior in AR mode in Scene Viewer . Set to "fixed" to disable scaling of the model, which sets it to always be at 100% scale. Defaults to "auto" which allows the model to be resized.

Provides augmented reality on supported iOS 12+ devices via AR Quick Look, but requires an additional USDZ model.

Set this attribute to control which iOS browsers will be allowed to launch AR Quick Look on iOS. Allowed values are "safari" and "chrome". You can specify any number of browsers separated by whitespace, for example: "safari chrome". Defaults to "safari".

Provides augmented reality on Magic Leap's Helio browser. Requires that the primary model be a GLB file, and the @magicleap/prismatic library.

• Astronaut by Poly , licensed under CC-BY .

• Español – América Latina
• Português – Brasil
• Tiếng Việt

The <model-viewer> web component

Adding 3D models to a website can be tricky; <model-viewer> is as easy as writing HTML.

Adding 3D models to a website is tricky. 3D models are ideally shown in a viewer that can work responsively on all browsers including smartphones, desktop, or even new head-mounted displays. The viewer should support progressive enhancement for performance and rendering quality. It should support use cases on all devices ranging from older, lower-powered smartphones to newer devices that support augmented reality. It should stay up to date with current technologies. It should be performant and accessible. However, building such a viewer requires specialty 3D programming skills, and can be a challenge for web developers that want to host their own models instead of using a third-party hosting service.

The <model-viewer> web component, however, lets you declaratively add a 3D model to a web page, while hosting the model on your own site. The goal of the component is to enable adding 3D models to your website without understanding the underlying technology and platforms. The web component supports responsive design, and use cases like augmented reality on some devices. It includes features for accessibility, rendering quality, and interactivity.

What is a web component?

A web component is a custom HTML element built from standard web platform features. A web component behaves for all intents and purposes like a standard element. It has a unique tag, it can have properties and methods, and it can fire and respond to events. In short, you don't need to know anything special to use any web component, much less <model-viewer> .

This article covers features that are particular to <model-viewer> . If you're interested in learning more about web components, webcomponents.org is a good place to start.

What can <model-viewer> do?

The following examples demonstrate some capabilities of <model-viewer> .

Basic 3D models

Embedding a 3D model is as simple as the following markup. By using glb files , this component will work on any major browser.

That code renders like this:

Add motion and interactivity

The auto-rotate and camera-controls attributes provide motion and user control. Those aren't the only possible attributes. See the documentation for a complete list of attributes .

Delay loading with poster images

All 3D models take time to load, adding a poster attribute means that an image will be shown until the model is ready to use. A poster image that will look identical to the 3D render can be generated using the editor .

Responsive design

The component handles some types of responsive design , scaling for both mobile and desktop. It can also manage multiple instances on a page and uses Intersection Observer to conserve battery power and GPU cycles when a model isn't visible.

Using the editor described previously to create a poster image allows that single image to match the 3D render, even as the aspect ratio of <model-viewer> responds to different screen sizes.

More features

Explore the <model-viewer> documentation for demos of more advanced features. These include the ability to add a ground-projected skybox , and create animated textures , and hotspots .

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License , and code samples are licensed under the Apache 2.0 License . For details, see the Google Developers Site Policies . Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-03-08 UTC.

Framing & Scaling

Camera view

Shadow intensity

Interaction

These scripts go into your head tag.

This is the modelviewer including all your hotspots. *NOTE: you'll have to put the folder directory inside the model-viewer src tag.

This is the css for the hotspots and annotations. *NOTE: annotations will always be visible.

View in English

Built-in apps, such as Safari, Messages, Mail, News, and Notes, use Quick Look to display USDZ files of virtual objects in 3D on iPhone, iPad, and Apple Vision Pro. You can embed Quick Look views in your apps and websites to let users see incredibly detailed object renderings in a real-world surrounding with support for audio playback.

Examples with animations

Quick Look supports built-in behaviors and animations in the AR experiences you create. Experience the interactivity of Quick Look* in the For All Mankind: Explorable Objects examples below.

Tap any of the 3D models below on a iPhone or iPad to view the object and place it in AR.* Or click a model on Mac to download the USDZ file.

Examples with banners

Quick Look enables you to add Apple Pay integration or custom actions to engage your users. Experience the power of custom actions in Quick Look* in our models below.

Examples on the web

The Metropolitan Museum of Art has produced an AR model in USDZ format of a wooden deity figure (zemí) from the Caribbean. This model leverages the new ability of Quick Look to be able to play an audio track while viewing the model.

Zemí Cohoba Stand

Huracán EVO RWD Spyder

• Español – América Latina
• Português – Brasil
• Tiếng Việt
• Documentation

Thanks for tuning in to Google I/O! Watch AR content on-demand .

Augmented reality with <model-viewer>

The <model-viewer> web component can be used to view and interact with 3D models on the web, and it seamlessly transitions to placing and interacting with those 3D models in Augmented Reality on the web.

When viewed on an ARCore-supported Android device, a <model-viewer> component with the ar attribute displays a button as shown in the following example:

Tapping this button on ARCore-supported devices will display the model using Chrome's WebXR functionality or the Scene Viewer app , depending on the value of the ar-modes attribute.

The appearance of the AR button can be customized by using web component slots. Refer to the <model-viewer> documentation for an example. See also, Scene Viewer for more about displaying interactive 3D models in AR from an Android app or browser.

Getting started with <model-viewer>

The following steps show how to get started with <model-viewer> on any webpage.

Add the <model-viewer> dependency

From unpkg cdn.

Then, add <model-viewer> at node_modules/model-viewer/dist/model-viewer.min.js using your preferred bundler,

Include the <model-viewer> tag

Add the <model-viewer> web component to your HTML document:

Configure the <model-viewer> tag

The model display can be configured by changing the attributes on the <model-viewer> tag. These properties expose options such as camera movement, model animations, and environment information. The <model-viewer> documentation lists all attributes that can be set. The Model Editor utility can generate a <model-viewer> HTML tag and configure properties such as camera position and lighting.

Model compatibility

Models in the gltf and glb file format are supported by <model-viewer> . Refer to the three.js GLTFLoader documentation for a list of supported glTF extensions.

To ensure that your model will display properly, check your model in Model Editor .

Browser and device support

Using <model-viewer> to display 3D models in a web page is supported in all evergreen browsers. We recommend using a :focus-visible polyfill to hide focus rings when the element is focused.

AR features require an ARCore-supported device and an installation of Google Play Services for AR . For the webxr AR mode , refer to WebXR browser support . By default, if WebXR is not supported, Scene Viewer will be used instead.

• Review the <model-viewer> reference documentation
• Check out <model-viewer> samples on modelviewer.dev
• See also, Scene Viewer for more about displaying interactive 3D models in AR from an Android app or browser.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License , and code samples are licensed under the Apache 2.0 License . For details, see the Google Developers Site Policies . Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2022-02-01 UTC.

Augmented Reality on the Web with Model Viewer

A tale of our team building a web ar experience using google’s model viewer..

IKEA’s mobile app to see furnitures on a room through the device camera, became pretty popular some time ago. Currently, the AR market is more looking for AR solutions that do not require the user to download an app. It should not be a surprise that big players like Apple and Google have done something similar to IKEA: they both developed a solution to see 3D models on real life, through the user phone camera.

Users can move and resize any 3D model in order to place it on the space, and see how it will fit on the room. They can also take pictures, in order to share the result with friends. This is really useful in some cases, for example for e-commerce sites or to create situated art experiences.

Apple and Google both succeeded in bringing these experience to the Web, so the users can reach them using an URL or a QRCode, without install ant app on their phones. Apple has done a ‘fake Web’ AR solution, while Google has followed a more ‘real’ Web approach, using WebXR Device API when supported, otherwise falling back to a native scene.

But most of the times, the user does not care about the trick under-the-hood, they only care about the magic they see. I’m going to explain this magic to you, with a tutorial-like article showing our use-case of a real business project for the Bologna Children’s Book Fair 2020 .

Model Viewer

Apple’s AR solution is called Quick Look. Google’s one is called Scene-viewer. But Google built something more: a Web Component, available as Open Source, that can be embedded in every Web page, and triggers either Quick Look (if the device is iOS based, and support it) or Google Scene-Viewer (if device has Android and ARCore libraries). They practically built one solution for every supported device, iOS or Android based. They called it Model Viewer. 

You can use Model Viewer either to show a 3D content embedded on a classic web page, to trigger Augmented Reality or both. According to the parameters of the HTML tag the user define, Model Viewer will behave differently. Before going into this story, that will act as a tutorial for you to start with Model Viewer, let’s have an overview with pros and cons of this technology:

• Easy to build: as you will see, only few lines of HTML are required
• Cross-platform: it supports iOS devices, Androids’ ones and also uses the new WebXR Device API technology if supported 
• Easy to use: the experience is straightforward for the users, they can move the object on the space, resize it and take pictures with few gestures.
• Easy to use — for programmers: I said it’s “easy”, but only if you’re able to write code. Currently, it does not support any official tool to build Model Viewer experiences without code. It can be seen as a missing feature, as the current trend in AR is to have AR Authoring Platforms to build experiences without coding knowledge
• Not cross-device: it’s cross-platform, but it’s far to be considered cross-device: it supports only iOS from version 13 ( see here for iOS distribution ), and Androids from this list . WebXR fallback is still far to be an option for cross-browser/cross-device support
• Not customisable: here’s one of the major lacks. You can only customise the first landing page, where the “AR triggers” relies. You cannot edit the “real” AR experience that you trigger when you click on “start AR” button. We will touch this point later in detail
• Feature detection: impossible on iOS and tricky on Androids. We will see this in detail too.

A real use case: Giving Life To BCBF at Home

As Chialab we are providing the Visual Identity and Communication consulting for the Bologna Children’s Book Fair from several years now. For this year’s edition, the first Virtual edition ever due to the pandemic crisis, we have designed and developed a way to bring the fair’s spirit into the users houses. Keep in mind that this fair happened during the pandemic lockdown, so we thought of a way to bring joy and to make the users feel like they were on the physical fair, as much as possible. During physical fairs we often created totems and visual artefacts and placed them all around the fairs buildings. So we thought that an engaging experience was to make the users place those artefacts — bounded to the fair visual identity —  appear on the users’ spaces, in front of their computers, on their living room, over their beds.

The idea was to give life to the fair spirit into the users houses. We thought about using Augmented Reality in several ways, and to use different technologies. We had these requirements:

Easy to use for the user

The user has to be able to see the artefacts as it was really on the room

No mobile app installation/search on the app store, so the idea was to use WebAR (Web Augmented Reality).

Given these requirements, we thought of using Model Viewer, we tried it and we adapted it according to our needs. Let’s see how.

Create your assets

First of all, when using Model Viewer, your assets has to be 3D models. But we started from 2D flat images. So our solution was to create flat 3D models that looked like 2D panels with the image as full texture. We started from a set of drawn avatars, scan them to make digital copies and then created 3D models out of them.

We used the Blender software in order to create 3D flat models from 2D images. Here’s a video tutorial from Fran Brennan. Model Viewer supports GLB, GLTF, DRACO and USDZ file formats. We used GLB (as GLTF but a single file) and USDZ in order to support iOS devices. If you want to support also Apple’s devices you have to create them. There is a free command-line tool — as far as I know only available on MacOS — that converts a GLB model into USDZ file. Here you can find information about it.

We ended up with five different 3D models, both with GLB and USDZ formats. It was time to look into the code.

The HTML snippet above can be embedded into any HTML page. You just have to import, on the HTML head section, the Model Viewer libraries (snippet taken from the official Model Viewer Documentation):

Let’s see the properties we have added (note, there are many more of them, we just used the ones we needed):

“data-name” is used by us to retrieve the specific element, in order to handle some actions and specific CSS styles

“src” and “ios-src” refers to the local 3D models, the first for Androids and the second for Apple’s devicesar activates the AR mode (technically it shows the AR trigger button, that when clicked by the users, activate the AR mode if available)

“ar-modes” specifies the AR technologies to trigger. The defaults are WebXR Device API, Scene Viewer and Quick Look, with this order. Model Viewer tries the first of the list and falls back to the others if does not find a full compatibility. We removed the WebXR Device API from the list because we found that does not work as of September 2020. So the effect was that it activates (on those Androids with updated Chrome and ARCore installed) but gives a black screen. So we decided to define only Scene Viewer and Quick Look

“camera-controls” and “auto-rotate” enable an auto-rotation of the model when it’s on the flat-view — the view before entering AR. You can also control it and rotate it using mouse/keyboard if you define the camera-controls 

“poster” can be used to change the look of the model on the page, before the user interacts with it. So if you want to show a different image (maybe an image with a text, for example) you can specify it with this attribute, otherwise the 3D model flat-view will be enabled as default.

What happens if a user with a non-compatible phone clicks on the 3D model in order to see it in AR? The feature-detection is not great, I have to admit. It appears that there were important updates on the latest Model Viewer version, and now at least it is possible to listen for an event and an attribute change that tells you if the phone is not compatible. But that happens after the user has clicked on the 3D model. So actually it is not possible to do an upfront feature detection. Furthermore, the event handling is only possible with Androids, but this is not a big deal as Apple support is much better in this case. 

Let’s talk about the support before seeing it in action.

Know your limits

First, Apple devices: it seems from some non-official Apple Twitter accounts that Quick Look (or Model Viewer) works great from iOS 12. We found that it is not true, iOS 12 is apparently not supported according to our tests (and that seems to be related to an Hardware limitation. Probably Quick Look works only with A10 chipsets, so iPhone 7 and above). Quick Look is well supported from iOS 13 (now also on iOS 14). That is good news, as according to this June 2020 report from Apple , it means that covers more than the 80% of iPhones around and more than the 70% of the iPads. This number are going to increase as the iOS 14 adoption will grow. 

We have to say that once an Apple device supports Quick Look, the AR experience is terrific: no lags, resize and rotation of the 3D model are easy to do and also the camera function works great. We are very happy from the Apple implementation.

We cannot say the same for the Androids. First of all, the support is not very clear: we have this list of ARCore supported devices, but we found that to have a smartphone listed in there does not mean that Scene Viewer (Model Viewer) will work. When the Scene Viewer is supported and the AR experience is triggered, the performances depend on the device specs. We found a laggy and memory-consuming experience even on powerful smartphones like the Huawei P20. That happens sometimes, other times the experience is good. The better the specification of the device, the better the experience.

What we are saying is: you probably have to handle yourself the feature detection, and provide a fallback experience if you want to deliver something to any user. You can show requirements and state that your AR experience works for iOS 13+ and latest Androids, so you will be sure that those that will try with Apple devices will found a great experience. For those with an Android device, you can feature-detect once they trigger the action (see paragraph above for detail) and then provide a fallback experience, maybe using a more supported Web AR technology (like AR.js , but be aware, AR.js does not support markerless and IKEA-like apps like Model Viewer, but it offers other cool features like Marker tracking, Image tracking and Location Based AR).

Bring content to our home

It’s time to see how Model Viewer works on the AR view. Once the user clicks on the poster or the 3D model flat-view, the AR scene will be triggered. From this point it is not possible for the developer to configure the experience, because it is not handled by the Web scene anymore. Quick Look or Scene Viewer are triggered and everything is handled by the smartphone’s OS.

You can see on the following GIF the experience from an iPad. The user can set the scene according to his/her needs and take pictures. You can create contests, and requests users to create funny and artistic scenes. Or you can just let the users be free to unleash their creativity and place the content wherever they want.

You can find the full video of the AR experience here, so you can have an idea of what you can expect from the Apple side of Model Viewer.

Here’s where you can find the Web AR app: https://bcbfar.chialab.io. Keep in mind the requirements specified above for the AR support.

What we learned

Google’s Model Viewer is a good way to start with markerless AR Ikea-style apps on the Web. It’s easy for designers and Web developers to implement a standard AR experience, a bit more difficult to handle fallbacks and a broader support for smartphones. If it’s not an issue for your project to have a broad support, it is good to provide this experience anyway, specifying the smartphone requirements.

It is a good way to build experiences that gives the users the freedom to create their scene and to take pictures to share. Last but not least, the Model Viewer team has recently released an editor to customise 3D models without using Blender or similar software, thus making the entire flux even more accessible. We suggest to keep an eye on Model Viewer updates, mostly the support for the WebXR Device API, that eventually will bring the chance to customise also the AR experience itself as it will be a true Web AR based tool, rather than a trigger for native scenes as it is now. 

Navigation Menu

Search code, repositories, users, issues, pull requests..., provide feedback.

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly.

To see all available qualifiers, see our documentation .

• Notifications You must be signed in to change notification settings

Safari IOS 15.4.1 (lasted) can't open AR mode #3384

{{editor}}'s edit

Jatumin01 apr 20, 2022.

Beta Was this translation helpful? Give feedback.

This is Apple's generic error for "couldn't parse the USDZ". Try exporting it again and ensure it's being served properly.

Replies: 2 comments · 3 replies

Elalish apr 20, 2022 maintainer.

jatumin01 Apr 21, 2022 Author

Seadeep42 apr 21, 2022.

vortice3D Oct 31, 2023

• Numbered list
• Unordered list
• Attach files

Select a reply

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.

Directly manipulate the scene graph

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.

Custom texture name

Image name from file name

Swap textures

Metallic-roughness

Transform textures

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:

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

Texture Type

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.

• Shoe ©Copyright 2020 Shopify Inc. , licensed under CC-BY-4.0 .
• Astronaut by Poly , licensed under CC-BY .
• Damaged Helmet by theblueturtle_ , licensed under Creative Commons Attribution-NonCommercial .
• Lantern , licensed under Creative Commons Zero .
• Water Bottle , licensed under Creative Commons Zero .
• Horse by Google Data Arts Team , licensed under Creative Commons Attribution-NonCommercial-ShareAlike .
• Duck by Sony Computer Entertainment Inc., licensed under the SCEA Shared Source License, Version 1.0 .