model-viewer

Features

🆕 Added localization API for a11y for WCAG compliance, thanks @cybmiper! #4715
🆕 Added Khronos PBR Neutral tone mapping standard ("neutral") - "commerce" is now an alias for this. #4716, #4760

Bug fixes

• Fixed USDZ auto-generation when changing baseColorFactor. #4690
• Fixed progress event reason propagation, thanks @rsleyland! #4701
• Fixed build problems related to imports, thanks @chamby! #4707, #4710
• Fixed DPR for iframes. #4723
• Fixed grounded skybox rotation. #4752
• Fixed USDZ rotation. #4753
• Fixed toBlob for offscreen elements. #4754
• Improved performance when model-viewer.js loads before a 3D element is visible, thanks @Arecsu! #4758

Examples

✨ Added example of a11y localization, thanks @cybmiper! #4715

Other notable changes

• Upgraded to Three.js r163. #4738, #4745
• Updated three-gpu-pathtracer comparisons, thanks @gkjohnson! #4686, #4696
• Added Blender Cycles to fidelity comparisons, thanks @vis-prime! #4492

Editor

• Removed some use of innerHTML (XSS security), thanks @Shivam7-1! #4748

Features

🆕 Added UltraHDR lighting support for 10x-30x smaller environments! #4578
🆕 Added skybox-height option to project an outdoor skybox onto the ground plane. #4604
🆕 Added AgX tone mapping and Commerce tone mapping is improved and no longer experimental! #4615
🆕 Added a reason property to the progress event, thanks @alexdaube! #4647

Bug fixes

• Improved AR button accessibility, thanks @Technickel-Dev! #4524
• Made CreateVideoTexture() respect with-credentials, thanks @navidadelpour! #4635

Examples

✨ Added example of toggling visibility of mesh variants. #4528
✨ Updated lighting examples for UltraHDR example. #4578
✨ Added Grounded Skybox example. #4604
✨ Added a tone mapping comparison example. #4615
✨ Small fixes for examples. #4514, #4627
✨ Added an FAQ on color accuracy, including links to longer write-ups on tone mapping and model validation. #4637

Other notable changes

• Upgraded to Three.js r160. #4610
• Added V-Ray support for emissive strength comparison, thanks @jasondavies! #4509
• Fixed Babylon transparency for fidelity comparisons, thanks @bghgary! #4531
• Switch from glTF-Sample-Models to the newer glTF-Sample-Assets, thanks @bhouston! #4534, #4546
• Add anisotropy tests to render-fidelity-tests (and update Babylon + Filament to latest), thanks @bhouston! #4535
• Update render fidelity main page to list renderers in a table, thanks @bhouston! #4539
• Enable complex arguments for "npm run render-goldens" command, thanks @bhouston! #4542
• Reduce time for fidelity test CI, thanks @bhouston! #4543
• Removed IE11-specific code, thanks @Frank3K! #4603
• Updated our commerce tone mapper for improved contrast and color accuracy. #4614

Editor

• Added open graph metadata to editor, thanks @Technickel-Dev! #4527
• Commerce tone mapping is now the editor default. #4615

Features

🆕 Added an experimental tone-mapping attribute to allow switching from our default, aces, to a new commerce function designed specifically for color accuracy in 3D commerce. #4495
🆕 Added zoom-sensitivity and pan-sensitivity attributes, thanks @nicolas-daures! #4412

Bug fixes

• Fixed sampler API that was leaking three.js internals. #4473, #4499, #4502
• Fixed variants normal map inversion. #4476
• Fixed glTF lights punctual support. #4477

Other notable changes

• Upgraded to Three.js r157. #4471, #4489
• Added V-Ray renders to fidelity comparisons, thanks @jasondavies and @bhouston! #4487

Editor

• Added a dropdown in the lighting tab to switch the tone mapping function. #4495

Bug fixes

• Fix npm postinstall script that was blocking install. #4359 #4363
• Fix not awaiting for QuickLook when activating AR in iOS, thanks @heatblayze! #4405

Other notable changes

• Removed Lerna in favor of npm workspaces. #4368 #4408

Features

🆕 Added optional post-processing API with a variety of rendering effects, thanks @Beilinson! #3948
🆕 Added an unbundled build, model-viewer-module.min.js, for use with post-processing or any others who need to de-duplicate three.js using import maps, thanks @Beilinson! #3948
🆕 Added anisotropy support. #4314, https://github.com/mrdoob/three.js/pull/25580
🆕 Added PBR Next material extensions API, including anisotropy, clearcoat, ior, iridescence, sheen, specular, etc. #4319, #4330, #4348
🆕 Added texture transform API to Sampler: setRotation, setScale, and setOffset. #4209

Bug fixes

• Fix transmissive objects losing color. #4314, https://github.com/mrdoob/three.js/pull/25819
• Fix webpack compilation warning, thanks @annahassel! #4350

Examples

✨ Added many post-processing examples, thanks @Beilinson! #3948
✨ Added transform textures example. #4209

Other notable changes

• Upgraded to Three.js r154
• Switched testing framework to modern-web and playwright. Also swapped jasmine for mocha in the space-opera tests. #4268
• Added postinstall script that updates the three importmap version, thanks @Beilinson! #4260

Bug fixes

• Avoid pointer lock-down. #4238
• Removed doubled period from alt text, thanks @ashleahhill! #4237
• Fixed setting currentTime when animation has not been played. #4231
• Improved glTF point-cloud support. #4228
• Fixed keyboard focus outline on Firefox and Safari. #4224

Other notable changes

• The focus-visible polyfill has been removed, since it is now supported in all major browsers. #4224
• Made peer dependency relationship clear in readme, thanks @johnnyshankman! #4202

Editor

• Adding hotspots now produces surface hotspots only for animated models and standard position & normal hotspots otherwise. #4228

Most of the updates this time were pulled from upstream in Three.js rather than directly in our code base. The big one is that our last major glTF compliance issue is now fixed: multiple UV channel and texture transform support! This means it's now possible to author GLBs with tiled textures, e.g. for fabric, and still have a non-tiled AO map. This can make for significantly higher-quality models with smaller file size.

Bug fixes

• Fixed video textures on iOS. #4141
• Proper support for multi-UV channel models. #4186
• Fixed loading failure for animations that target a missing node. #4186

Examples

✨ Fixed a bug in the annotations example, thanks @y-71! #4151

Other notable changes

• Updated Three.js to r151. #4186, #4192
• Updated fidelity comparison with v1.31.5 of Filament, thanks @bejado! #4138
• Removed last usages of unpkg from our editor and docs pages for increased reliability, thanks @cpiggott! #4196
• Added Web 3D Survey to served pages, thanks @bhouston! #4200

This does not change our bundled build, so most users will see no change compared to v3.0.1. This changes how our dependencies are represented in npm, which is important for developers that are incorporating <model-viewer> into a larger TS/JS project. Specifically:

• Removed lottie-web dependency - the animation object of a LottieTexture is now marked any, so please cast it with image.animation as import('lottie-web').AnimationItem; if you want type info. #4132
• Switched three.js to a peer dependency, allowing it to be shared within a project. This could be construed as a breaking change, but we're bundling it up as part of v3.0 since that was so recent. Just make sure three is installed and the build should continue to work. #4135

Bug fixes

• Fixed with-credentials, thanks @robertsLando! #4098
• Fixed updating hotspot's data-surface attribute. #4099
• Fixed slow video texture framerate on Firefox. #4105
• Avoid lottie-web dependency errors, thanks @robertsLando! #4108
• Fixed Lottie textures not updating. #4114

Examples

✨ Fixed animated hotspots example for iOS. #4107
✨ Fixed video textures example for Firefox. #4104
✨ Fixed Lottie textures example for Safari by demonstrating proper use of ES-module-shims. #4113
✨ Updated recommended CDN from unpkg to ajax. #4121

Other notable changes

• Updated default DRACO decoder to v1.5.6. #4115
• Updated fidelity comparison with v0.0.13 of three-gpu-pathtracer, thanks @gkjohnson! #4118
• Fixed Babylon.js renderings, thanks @Popov72! #4120, #4123

✋Breaking Change

• The KHR_materials_pbrSpecularGlossiness extension is no longer supported (renders white), as it has been deprecated for more than a year. This should affect only a small number of our users, but we're giving it a major version to call attention. Our Editor now supports auto-converting any uploaded Spec-Gloss model losslessly to use the modern extensions. If you need to batch-convert, gltf-transform has an excellent utility function. #3997

Features

🆕 Added dynamic hotspots, which follow a point on the model's surface while it animates. These can be generated by the surfaceFromPoint method, which the editor now employs. #3981
🆕 Added animated texture support, for video, canvas2D, and Lottie animations, which can be loaded and applied to any texture slot using our materials API. #3886

Bug fixes

• Apply with-credentials toggle to all loaders. #4085
• 'camera-change' event now fires in AR (WebXR mode only). #4067
• Various element lifecycle fixes. #4048, #4046, #4043, #4041
• Fire camera-change event at most once per animation frame. #4027
• Fix skybox and hotspots when an empty GLB is used. #4006
• Set texture anisotropy to 4 for improved oblique renders, thanks @hybridherbst! #4005
• Fix custom hash params interfering with USDZ auto-generation, thanks @milesgreen! #4004
• Make WebXR work on the Quest 2, thanks @cabanier! #3984

Examples

✨ Added animated hotspots example, which also demonstrates animated SVG pointers. #3981
✨ Added animated textures example. #3886
✨ Updated dimensions example to be more performant. #4027

Other notable changes

• Upgraded to Three.js r149
• Added three-gpu-pathtracer to render fidelity comparison, thanks @gkjohnson! #3496
• Added new glTF sample models to fidelity comparison, thanks @gkjohnson! #4069, #4070
• Fixed the fidelity page image comparison tool. #4074
• Added Stellar path-traced renders of new models, thanks @bsdorra! #4078
• Rearranged modelviewer.dev and added an FAQ page. #4011, #4012

Editor

• Added Spec-Gloss auto-conversion. #4063
• Allow testing AR by opening a model directly in the editor on a mobile device. #4024
• Added hotspots are now dynamic and will follow animated models. #3981
• Fixed scene export. #4086
• Fixed snippet export of saved initial camera state. #3970

Bug fixes

• Fixed rendering on iOS 15.2, thanks @Stynson! #3941
• Cancel interact() when disconnecting from DOM, thanks @samaneh-kazemi! #3964
• Fixed "basic" prompt not appearing, #3965

Features

🆕 Added queryHotspot() method to enable complex dynamic annotations linked to the scene, thanks @jukibom! #3844
🆕 Re-added interaction-prompt-style which was removed during the v2.0 cleanup, but was returned by popular demand. #3880
🆕 Enabled CSS-style color strings as input to setBaseColorFactor and setEmissiveFactor, giving automatic conversion of sRGB color values. #3931

Bug fixes

• Workaround for quick-look-button-tapped event not being fired on iOS 16, thanks @milesgreen! #3850
• When specifying the variant-name attribute, the default variant no longer blinks in during load. #3864
• Fixed some memory leaks when creating and destroying <model-viewer> elements. #3927
• Cleaned up docs titles, thanks @jessej-samuel! #3832

Examples

✨ Updated the Dimensions example to demonstrate SVG dimension lines using queryHotspot(), thanks @jukibom! #3844
✨ Simplified the Change Color example by setting CSS color strings directly. #3931

Other notable changes

• Upgraded to Three.js r146

Editor

• Fixed GLB export when variants are added to the model. #3863
• Fixed sRGB color conversion for chosen color factors. #3905

Bug fixes

• Ensure MV element adjacent to viewport is not treated as visible: #3835
• Fix canvas size bug for elements added after page load: #3836

Fixes model disposal on iOS < 15: #3816

We have been carefully following semantic versioning rules to avoid breaking changes for our diverse user base, but this has caused parts of our API to become less beginner-friendly as our newer best-practices have not become defaults. The time has come to reset with a v2.0 release!

The API simplifications have also allowed us to clean up our code base, easing maintenance and reducing the likelihood of future bugs.

To be clear, we still want to make updating to v2.0 easy for our users, so we're changing features that are little-used or will improve the experience on most sites. The changes to defaults can be overridden by specifying attribute values. Regeneration of poster images is strongly recommended. See discussion in #3460.

✋Breaking Changes

Updated Defaults

• Minimum radius is doubled to match the enable-pan default, with default field-of-view narrowed to 30 degrees (12 degree default minimum). This gives the default framing a "longer lens" with reduced perspective warp: #3668
• Default enable-pan to true, replacing the enable-pan attribute with disable-pan. Also added disable-tap attribute: #3713
• Switch touch-action default from pan-y to none: #3712
• Switch default environment-image to neutral, renaming the current default as legacy: #3676
• Enable USDZ autogeneration by default, by switching the ar-modes default to webxr scene-viewer quick-look: #3802

API Simplification

• Remove the 'bounds' attribute, making the behavior equivalent to bounds="tight": #3683
• Remove the deprecated scene-graph-ready event: #3700
• Remove the progress-mask; equivalent to setting its part to display: none;. This will keep the poster from appearing lightened during loading: #3692
• Remove the "interaction" option from the reveal attribute. Use "manual" and dismissPoster() instead to achieve this behavior: #3688
• Remove the interaction-policy attribute, allowing only the default "always-allow" behavior: #3686
• Remove the "when-focused" option from the interaction-prompt attribute: #3687
• Remove the interaction-prompt-style attribute, allowing only the default "wiggle" behavior: #3685
• Remove --poster-color, making the poster always have a transparent background: #3701
• Remove the seamless-poster attribute, making the behavior as though this option is always enabled. Note this in combination with the previous bullet means there is no longer a transition fade between poster and model, so seamless posters as generated by toBlob({idealAspect: true}) or our editor are strongly recommended: #3704
• Remove the Image.setURI method from our materials API. Use the createTexture method instead: #3710
• Update exportScene options to match three.js r143. Specifically, remove embedImages (always true now) and forcePowerOfTwoTextures. Add forceIndices: #3711
• Remove preload event, as there is no longer any distinction from the load event: #3799

TypeScript Updates

• Switch our package.json module to point to lib instead of dist. For JS users, main will still point to our bundle in dist, but this change will send TS users to our lib so they can build and tree-shake it themselves, which is best practice. Also, our lib already contains all our *.d.ts files: #3718
• Add types pointers to package.json as well as a fallback model-viewer.d.ts bundled types file, thanks @subhankar-trisetra! #3774, #3791

Features

🆕 Added External Renderer API to drive e.g. cloud-based or path-tracing renderers: #3482
🆕 Added Material API documentation: #3493
🆕 Added keyboard controls for pan, thanks @clochardM33! #3702
🆕 Added inputSensitivity property: #3719
🆕 Added getBoundingBoxCenter: #3734

Bugfixes

• Move the Exit AR button to the safe zone, thanks @yuta-hayashi! #3464
• Fix fractional pixel sizes causing some blurring, thanks @bcairns! #3555
• Fix positionAndNormalFromPoint() hitting the floor plane: #3599
• Fix skybox shown in AR when switching src: #3606
• Fix docs page build failure, thanks @demarijm! #3696
• Ensure the 'load' event fires after the pixels are properly rendered: #3702
• Make JS camera changes cancel interaction prompts and add "automatic" to camera-change event: #3717
• Improve WebXR wall-placement UX: #3736
• Fix error event detail: #3742
• Fix reveal changes causing rendering breakage: #3745
• Ensure dynamic render scaling always returns to full-res when the model stops moving: #3752
• Ensure exportScene is including scale/orientation changes: #3772
• Fix iOS AR feature detection for WebViews and iOS16, thanks @milesgreen! #3784
• Fix bounds calculation for quantized models: #3768

Other notable changes

• Updated to Three.js r144
• Dynamic render scaling is now less aggressive, targeting 15-20 fps before down-sampling
• Various loading performance improvements

Features

🆕 Added interact() method to create synthetic touch gestures that move the model; ideal for creating custom interaction prompts for rotation, zoom, and pan. #3320
🆕 Added 'poster-dismissed` event. Technically it's not new, but was undocumented.

Bug fixes

• Fixed ImageBitmap memory leak. #3399
• Fixed model cache, which was not properly caching GPU memory. #3417
• Fixed glTFs with unused extra texture coordinates rendering incorrectly. #3426
• Ensure the camera-change event is also fired for camera-target changes. #3427
• Updated criteria for detecting baked shadow planes (unlit no longer required). #3431

Examples

✨ Added a custom prompt example to demonstrate interact() and the finger slots. #3320
✨ Fixed zoom sensitivity in the camera views example. #3356

Other notable changes

• Switched to Pointer Events internally. #3404, #3418
• Upgraded to Lit 2, thanks @e111077! #3405, #3428

Bug fixes

• Fixed a pause/play animation regression: #3349
• Fixed a Windows morph target regression by pulling in three.js r139: #3350
• Tap in pan mode still recenters, but no longer zooms, by popular demand: #3351
• Keep pan sensitivity consistent across zoom levels: #3332
• Don't override user's oncontextmenu function: #3333
• Ensure the pan target appears and disappears correctly: #3354

Features

🆕 Added enable-pan attribute for two-finger or right/meta-click drag, as well as tap recentering. Note that enable-pan also changes the default framing, which will likely become the overall default in v2.0. #3286, #3319
🆕 Improved soft shadows! API is unchanged, but the look is significantly nicer (and softer). Note: you may want to regenerate poster images. #3182
🆕 Added hasBakedShadow() method and we now automatically remove these shadow planes from framing computations and disable them when shadow-intensity is set > 0 to avoid double shadows. Baked shadows are identified as axis-aligned planes with unlit, transparent material. #3295
🆕 Added render-scale event, to get analytics on when your users are GPU-throttling. #3307
🆕 Added timeScale to control speed of animation or play in reverse. Thanks @futahei! #3129, #3304
🆕 Allow textures to have their name set. Thanks @slightHYP! #3175
🆕 Fall back to selection of animation by index if name is not found. Thanks @prefrontalcortex! #3225
🆕 Added with-credentials attribute to load non-public models. Thanks @ymoriaud! #3239

Bug fixes

• Turn off tone mapping for Unlit materials. #3152, #3232
• Stop camera-target from shifting the model in WebXR AR mode. Thanks @futahei! #3171
• Fix out of range mesh when assigning variant userData. Thanks @alexdaube! #3195
• Remove unnecessary async/await in TextureUtils. Thanks @sukolsak! #3212
• Various accessibility improvements, especially reducing distracting annoucements. #3262
• Maintain texture transforms when new textures are set. #3263
• Fixed bounding box computation for animated models. Only applies with bounds="tight", which will become default in v2.0. #3272
• Fixed setAlphaMode for BLEND and MASK. #3306

Examples

✨ Added a render-scale example so you can test in real time how our dynamic render scaling operates on different devices and experiment with controlling it. #3307
✨ Dramatically simplified the panning example based on the now available attribute. #3286

Other notable changes

• Hopefully(!) fixed types import for TS users. Note: you'll need to import our /lib rather than the bundle. #3200
• Updated to Three.js r138. Includes an upstreamed improvement allowing any resolution of environment-image: https://github.com/mrdoob/three.js/pull/23322
• Added Dassault Systemes STELLAR path-traced renderer to our fidelity comparisons. Thanks @bsdorra! #3178
• Added details on developing in WSL environment to our README. Thanks @prefrontalcortex! #3230

Editor

• Added panning to the editor by default. #3286
• Added dimensions to the validation report (under Model Details) to help check AR scale. #3247
• Added an Alpha Factor slider to the materials editor. #3306

This is actually identical to v1.10.0, but a bad build was pushed to npm, so this is resolving that error.

Features

🆕 Added glTF sheen extension support! We now support all of the released PBR extensions. See fidelity comparisons here. https://github.com/mrdoob/three.js/pull/23069
🆕 Added repetitions and pingpong options to the play() method for better animation control. Thanks @futahei! #3021, #3104
🆕 Added uv coordinates to the output of positionAndNormalFromPoint(). Thanks @BR14Nx! #3043
🆕 Added a zoom() function to allow programmatic camera manipulation equivalent to keyboard/scroll/pinch zoom behavior. #3087
🆕 Default framing now accounts for non-default field of view. This means when you want a custom focal length, you no longer need to calculate and set a corresponding radius in camera-orbit. #3105

Bug fixes

• Fixed slow loading for identical models in multiple elements. ✋BREAKING CHANGE: the setURI method now changes a texture for all models that point to it. To individually change a texture when the same model has been reused, please use the newer createTexture API. #2935
• Fixed setAlphaMode. Thanks @SrirachaSource! #2985
• Reduced shader re-compilation to improve performance. #3045
• Fixed clicks causing extra progress bar advancement. Thanks @mehak08g! #3077
• Workaround for a Safari 15 bug that was causing textures to randomly show up black. #3082
• Output now correctly uses sRGB encoding rather than gamma. This slightly lightened our renders, so you may want to regenerate seamless poster images. #3082
• Fixed some subtle camera errors. #3087
• Fixed variant switching error. Thanks @SrirachaSource! #3086
• Fixed Windows loading performance regression (properly this time). #3004
• Made progress bar advance more linearly. #3110, #3111

Examples

✨ Added Thor camera views example. Thanks @hybridherbst! #3018
✨ Fixed example strings. Thanks @benmbark! #3040
✨ Updated transparency example to demonstrate glTF transmission support. #3112

Other notable changes

• Updated to Three.js r136. Includes an upstreamed performance improvement for PBR: https://github.com/mrdoob/three.js/pull/22998
• Made a generic 3D Twitter player card and a generator for anyone to quickly customize their own. #3026, #3031, #3036, #3038
• Improved developer experience by unpackaging shared-assets and shallow-cloning Khronos sample models. #3079

Editor

• Added variants editing support. Thanks @SrirachaSource! #2929, #2984
• Added poster download button. #2928, #3059
• Fixed BasisU texture support. #3039
• Added meshopt support. #3089
• Added a Reset Framing button. #3105