AR.js: marker, image and location AR in the browser

What AR.js solves, and for whom

The library targets a narrow but common problem: putting AR content into a page that is already a web page. There is no app store submission, no native SDK, no separate build target for iOS and Android. The README describes AR.js as "a lightweight library for Augmented Reality on the Web, coming with features like Image Tracking, Location-based AR and Marker tracking."

The audience follows from that. It suits web developers who can write HTML and a little JavaScript and who already have a three.js or A-Frame scene. It suits people who need a printed target, such as a product card, a poster, a sticker or a page in a book. It suits location experiences where content is anchored to a latitude and longitude rather than to a visual feature. It does not suit teams who need the camera to understand an arbitrary room. The README's own update note points readers who need image tracking and face tracking toward MindAR, and adds that "as for now, AR.js is still the only library providing Marker based and Location based AR features." That is the maintainers' framing, not an independent benchmark, but it explains the project's position accurately enough: the niche is markers and coordinates.

How the tracking pipeline is wired

The repository is a build system around two consumers of the same core. The top level holds aframe/ and three.js/ directories, and webpack.config.js drives the bundling. The package.json declares @ar-js-org/artoolkit5-js, aframe and three as dependencies, so the tracking math comes from artoolkit5-js while the rendering comes from whichever framework you picked.

The README is explicit that the builds are exclusive. There are two A-Frame builds and three three.js builds, and you import the one you need, not both. The A-Frame pair is aframe-ar-nft.js for image tracking plus location, and aframe-ar.js for marker tracking plus location. On the three.js side, ar-threex.js covers image and marker tracking, ar.js exposes the ARjs namespace, and ar-threex-location-only.js is location only.

Location tracking works differently from the other two. There is no computer vision involved. The README's geo example asks you to put in your latitude and longitude and to activate GPS on your phone. This is why the geo example can show text that faces the viewer from a fixed coordinate, and why it degrades wherever GPS is weak.

Installing AR.js and running a first marker scene

There is no package install step for the browser case. The README distributes the builds as script tags from raw.githack.com, and the npm package name is @ar-js-org/ar.js with main pointing at ./aframe/build/aframe-ar.js. The README also shows how to pin a version by replacing the master segment of the URL with a tag:

<script src="https://raw.githack.com/AR-js-org/AR.js/3.4.8/aframe/build/aframe-ar-nft.js">

That is the whole installation for a page. Note that the repository's own test script is a stub: package.json defines "test" as an echo that exits with an error, so npm test runs no tests, even though a test/ directory exists. The npm scripts that do something are build, build:dev, server and the prettier format targets.

If you are working from a clone rather than the CDN builds, the scripts are:

npm install
npm run build
npm run server

The build runs webpack in production mode, and server starts npx http-server -c -1, which serves the working directory on a local port with caching disabled. That last flag matters during development, because a cached AR build is a confusing thing to debug.

The README's image tracking example is the shortest path to a working scene. It loads A-Frame 1.6.0, then the NFT build, plus a .arjs-loader style for the loading overlay.

The README's steps are to create the project, run it on a server, open the site on your phone, and scan the supplied trex picture. One warning applies before you copy it: the README says external resources, especially for NFT, cause CORS problems unless they sit on the same server as your code, and that the correct fix is to place them there.

For a marker scene, the mechanics are the same but the target is a printed marker image rather than a trained descriptor set, and the build is aframe-ar.js instead of aframe-ar-nft.js. The README's marker example uses an a-marker element with preset="hiro" and links a live example and the hiro picture to scan.

Where AR.js stops being the right tool

The most concrete limitation is that the tracking modes are the product. If your experience depends on knowing where the floor is, AR.js cannot tell you. The README's feature list names no plane detection, depth or occlusion. Marker and image tracking both answer a narrower question: where is this known target in the camera frame. Location tracking answers where the device is on the planet, with the accuracy the GPS gives you. Anything outside those questions is your problem.

The README's image example has you scan a supplied trex picture and does not cover preparing your own image; it points to the official documentation for more.

The location mode has its own failure surface. It reads GPS and device orientation, so it is only as good as the sensor fix and the compass. Indoors, in a city canyon, or on a device with a poorly calibrated magnetometer, placed content drifts or spins. The README's geo example is honest about the intended effect: the text appears in the requested position and keeps facing you as you move. That is a demonstration of the coordinate mapping, not a claim about positional accuracy.

There is also a maintenance signal worth reading plainly. The last push to the default branch was on 2026-06-21, and the most recent release listed is 3.4.8 from 2026-03-16. The repository is not archived. The README itself notes that the project changed hands, from its creator to Nicolò Carpignoli, and is now maintained by the AR.js org.

AR.js against MindAR and against plain WebXR

The README names the alternative itself. MindAR is described there as a separate open source web AR library, recommended for image tracking, including multiple images, and for face tracking. The difference in approach is visible in that sentence: MindAR's strength is the tracking mode AR.js does not have, faces, and multi-image tracking. If your project is a face filter or needs several images tracked at once, AR.js is the wrong starting point and the README says so.

The comparison against raw WebXR is a different axis. WebXR is a browser API, not a library, and it is what you would use if you wanted to build the tracking yourself or lean on the device's native AR capabilities. AR.js does not depend on WebXR for its tracking; it does its own vision work through artoolkit5-js and reads GPS and orientation sensors for the location mode. The trade is that you inherit artoolkit's constraints, and you get markers and coordinates rather than the surface understanding a native AR runtime provides.

A-Frame and three.js are not alternatives to AR.js so much as the layer beneath it. The README ships builds for both, and package.json lists both as dependencies. Choosing between them is choosing your scene graph, not choosing your tracker.

Licence, upgrade cost and what a version bump means

The licence is MIT, stated in package.json and in the LICENSE file at the repository root. In practical terms that is a permissive licence, and the usual obligations attach: keep the copyright notice and the licence text with the distribution. This is not legal advice, and if you are embedding the library in a product with its own licensing constraints, that is a question for your own counsel.

Upgrading is cheap if you load the builds from a CDN, because the version is in the URL. The README shows the pattern: replace master with a tag such as 3.4.8. That also means you can pin and forget, which is the safer default for a production page. The release cadence visible in the repository is uneven. 3.4.6 landed on 2024-12-22, 3.4.7 on 2025-02-07, and 3.4.8 on 2026-03-16, about thirteen months later. There is a CHANGELOG.md at the root, and HOW_TO_RELEASE.md documents the release process for maintainers.

If you build from source instead, the upgrade cost is the webpack toolchain. The devDependencies pin webpack 5, webpack-cli 7 and worker-loader 3, and there are simple-git-hooks and lint-staged configured for a pre-commit prettier run. A major bump in any of those is your problem to absorb, not the library's.

Editorial conclusion

Adopt AR.js when your AR content is a printed marker, a trained image or a GPS coordinate and the rest of your product is already a web page. Do not adopt it for surface detection, occlusion or face tracking, because the README lists only image, location and marker tracking and points face tracking to MindAR. Before committing, verify two things on a real phone: that your assets are served from the same server as your code, as the README advises to avoid CORS problems, and that the marker or image still locks at the distance and angle your users will actually hold the camera.

Frequently asked questions

Official sources

1. AR-js-org/AR.js on GitHub
2. Issues
3. License: MIT
4. README
5. Releases