google/model-viewer: a web component for interactive 3D and AR, and where it stops

The gap <model-viewer> fills between a 3D file and a web page

Shipping a 3D asset to a browser normally means writing WebGL, wiring up a camera, handling lighting and materials, and then repeating the work for every model on the site. The <model-viewer> web component collapses that into a custom element. You point it at a glTF or GLB file and the component handles the scene, the default environment lighting, camera controls and the poster image that shows while the asset loads. The repository describes itself as the main GitHub repository for the web component and all of its related projects, and the package most readers want lives under packages/model-viewer.

The audience is front-end engineers and product teams who already have models exported from a DCC tool or a photogrammetry pipeline. It is not for people who need to build or edit geometry in the browser. That job belongs to the separate editor under packages/space-opera, which the README links as the source of the <model-viewer> editor. The component itself is a display surface.

What the monorepo actually contains

This is not a single npm package with a docs folder. The root package.json declares npm workspaces for five packages: model-viewer, model-viewer-effects, modelviewer.dev, render-fidelity-tools and space-opera. The root is private and marked as type module, so the workspace layout is the unit of development.

model-viewer-effects is a PostProcessing plugin for the component, which is how you add effects beyond the default rendering. modelviewer.dev is the source of the documentation site at modelviewer.dev. render-fidelity-tools exists to test how well the component renders models, which tells you the project treats visual accuracy as something to measure rather than assume. shared-assets holds models and environment maps reused across sub-projects. space-opera is the editor.

The practical consequence is that cloning the repository is heavier than installing the component. The README notes that depth=1 keeps you from downloading roughly 3GB of history, dominated by versions of the golden render fidelity images. If you only want the component in an application, you do not need this repository at all.

Installing google/model-viewer and rendering a GLB

For application work, the component is consumed as a package. The README for the repository is aimed at contributors, so the install path for consumers is the packages/model-viewer README and the documentation site rather than the root file. The element name is model-viewer, and the source attribute points at a glTF or GLB asset. The documentation site holds the attribute reference and the examples, so the exact attribute set is worth reading there rather than guessing.

The root README gives the contributor sequence. It requires git, Node.js and npm, then:

git clone --depth=1 [email protected]:google/model-viewer.git
cd model-viewer
npm install

The root package.json sets engines.node to >=12.0.0. After install, npm run build runs the build step across all sub-projects, npm run serve starts a web server pointed at the local copy of modelviewer.dev, and npm run test runs tests in sub-projects that have them. The README warns not to forget to build before serving. The npm ci command installs dependencies and cross-links sub-projects, and npm run clean removes built artifacts from all sub-projects.

Windows and WSL: the setup the README recommends

The Windows story is explicit and somewhat unusual. The README states that due to dependency issues on Windows 10, setup should run from a WSL2 environment, with Node.js and npm installed via NVM. It also says to clone from inside WSL rather than from Windows, because otherwise you may hit line endings and symlink issues, and it suggests HTTPS over SSH inside WSL because of known file permissions issues with SSH keys there.

For that WSL path the README gives a specific clone and install sequence:

git clone --depth=1 https://github.com/google/model-viewer.git
cd model-viewer
npm install

Running tests in WSL requires binding CHROME_BIN to the Windows Chrome executable:

export CHROME_BIN="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
npm run test

The README notes that packages/model-viewer and packages/model-viewer-effects tests should run with that setup, but fidelity tests need GUI support, which it says is only available in WSL on Windows 11. One documented failure mode is a line-ending error, /bin/bash^M: bad interpreter, caused by git rewriting .sh files on checkout outside WSL. The suggested workaround rewrites the file with sed. The README also records a Windows-only error, Task not found: "'watch:tsc", when running npm run dev in packages/model-viewer, and notes that no solution is documented.

Where <model-viewer> is the wrong tool

The component renders glTF and GLB. It is not a converter, so a STEP file, an FBX export or a proprietary CAD format has to be converted before it reaches the element. Teams that expect a viewer to open anything will be disappointed, and the repository does not present itself as that.

It is also a browser technology. The AR path depends on the device and browser supporting the relevant web AR modes, and the README material does not promise parity across platforms. If your requirement is a desktop viewer for Windows, this is not the project, and the search results around Windows viewers point at a different category of software entirely.

There is a maintenance question too. The last push to the default branch was on 2026-07-07, and the most recent release listed is v4.3.1 from 2026-06-04. That is a real cadence, but it is not a project that ships weekly, so a team that needs a fix merged on its own schedule should read CONTRIBUTING.md before planning around it. The repository is not archived.

Alternatives and the actual difference in approach

The closest alternative in the topics list is three.js, which this project builds on. The difference is the level of abstraction. three.js gives you a scene graph, renderer, loaders and controls, and you write the integration: creating the canvas, sizing it, handling resize, choosing lighting, and wiring the loading state. <model-viewer> packages a specific, opinionated version of that integration into a custom element, which means less code and less control. If you need a non-standard camera rig, custom shaders applied to the whole scene, or a render loop that reacts to application state, three.js is the better fit and <model-viewer> will feel like a wall.

If you need effects, the repository's own answer is model-viewer-effects, a PostProcessing plugin for the component, rather than dropping down to three.js. That keeps you inside the element's model of the world.

For authoring rather than display, the comparison is the space-opera editor in the same repository, which is a different product with a different purpose. Choosing between them is not a technical trade-off; it is a question of whether your users need to change the model or look at it.

Licence, maintenance and what an upgrade costs

The repository is licensed Apache-2.0, and the root package.json carries the same identifier. Apache-2.0 permits commercial use and modification and includes an express patent grant, with the usual obligations around notices and stating changes. That is a permissive licence, but it is not legal advice, and distribution models that embed the component in a packaged product should be reviewed by whoever handles licensing at your organisation.

The upgrade cost is dominated by the fact that the component is a custom element with attributes and events. Pinning a version and reading the release notes between v4.2.0, v4.3.0 and v4.3.1 is the practical approach. The heavier cost sits on the contributor side: the monorepo requires npm install across five workspaces, a build step, and on Windows a WSL2 setup with CHROME_BIN exported before tests run. If your team only consumes the published package, that cost does not apply to you.

Editorial conclusion

Adopt google/model-viewer if you already have glTF or GLB assets and need them on a page with AR handoff, and you accept that the component renders rather than edits. Do not adopt it as a 3D authoring tool, a general-purpose viewer for arbitrary formats, or a Windows-native application. Before committing, verify that your target browsers are covered by the AR modes you need, check the Apache-2.0 licence against your distribution model, and confirm the last push date (2026-07-07) fits your tolerance for a project that is not on a fast release cadence.

Frequently asked questions

Official sources

1. google/model-viewer on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases