A helper three.js library for building AR web experiences that run in WebARonARKit and WebARonARCore
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add issue/pr templates and move COC/Contributing files to .github dir Nov 21, 2017
dist 0.1.8 Feb 26, 2018
examples Removed the iphonex example (added it in the previous commit by mista… Feb 16, 2018
src save and configure extra values we need, then restore when we're done Feb 20, 2018
third_party updated to threejs r90 Mar 2, 2018
.babelrc Switch to rollup for reduced output size and potential es6 module future Nov 13, 2017
.eslintrc Add space-infix-ops eslint rule Oct 26, 2017
.gitignore Commit package-lock.json Oct 20, 2017
.npmignore Adding screencaps to README Aug 30, 2017
.travis.yml Update eslint, fix spacing lint errors, remove node 6 from CI tests Dec 21, 2017
API.md Add API documentation for ARAnchorManager Mar 2, 2018
LICENSE Iniitial commit Aug 8, 2017
README.md Clarify documentation on publishing Feb 26, 2018
licenses.txt Switch to rollup for reduced output size and potential es6 module future Nov 13, 2017
package-lock.json 0.1.8 Feb 26, 2018
package.json 0.1.8 Feb 26, 2018
rollup.config.js Add support for building as ES module via three.ar.module.js Jan 4, 2018
rollup.config.min.js Fix minified builds from changes in adding module support in #89 Jan 12, 2018
webvr_ar_extension.idl Improved the documentation for anchors and markers according to the P… Jan 12, 2018
webvr_ar_extension.md Improved the documentation for anchors and markers according to the P… Jan 12, 2018



Build Status Build Status Build Status Build Status

A helper three.js library for building AR web experiences that run in WebARonARKit and WebARonARCore.

Spawn-at-Surface example, for ARCoreSpawn-at-Camera example, for ARKit

WebARonARKit and WebARonARCore are experimental apps for iOS and Android that let developers create Augmented Reality (AR) experiences using web technologies. three.ar.js makes it easier to create these experiences by providing helper classes and utilities on top of the three.js 3D library, which interfaces with the WebVR Extension for AR exposed by WebARonARKit and WebARonARCore. For example:

  • THREE.ARReticle: a visible reticle drawn on the real surface of real world objects.
  • THREE.ARPerspectiveCamera: a camera that matches your three.js scene to your camera's video feed.

See three.ar.js API documentation for details.



<script src="https://cdn.jsdelivr.net/npm/three.ar.js@latest/dist/three.ar.js"></script>
<!-- or the minified version -->
<script src="https://cdn.jsdelivr.net/npm/three.ar.js@latest/dist/three.ar.min.js"></script>


Download the build at dist/three.ar.js and include it as a script tag in a web page. You must include three.js as well, and three.ar.js must be included after.

<script src='three.js'></script>
<script src='three.ar.js'></script>


If you're using a build tool, like browserify or webpack, install it via npm. Note you must also have three.js installed via npm.

$ npm install --save three three.ar.js


Accessing three.ar.js depends on the environment you're working in. Below are examples of importing the code via script tag, as well as a module bundler like browserify or webpack.

To view the additional APIs implemented by WebARonARKit and WebARonARCore, view the WebVR Extension for AR document.

For more examples, see the examples/ directory.

See the full three.ar.js API documentation for more details.


If you are including three.ar.js via script tag, the additional three.ar.js features are appended to the THREE namespace, for example:

 * Not a full working example -- see the `examples/` directory

function init(display) {
  vrDisplay = display;
  // Set up three.js scene
  renderer = new THREE.WebGLRenderer({ alpha: true });
  scene = new THREE.Scene();

  // ...

  // Set up our ARView with ARPerspectiveCamera
  arView = new THREE.ARView(vrDisplay, renderer);
  camera = new THREE.ARPerspectiveCamera(vrDisplay, 60, window.innerWidth / window.innerHeight, vrDisplay.depthNear, vrDisplay.depthFar);
  vrControls = new THREE.VRControls(camera);


function update() {
  // Update our controls/camera, the ARView rendering,
  // and our three.js scene
  renderer.render(scene, camera);


If you're in a browserify or webpack like environment, three.ar.js uses three.js as a peer dependency. This means you can import both packages separately.

import { Scene, WebGLRenderer } from 'three';
import { ARUtils, ARPerspectiveCamera, ARView } from 'three.ar.js';

async function init() {
  const display = await ARUtils.getARDisplay();
  const renderer = new WebGLRenderer({ alpha: true });
  const arView = new ARView(display, renderer);

  // And so forth...


If you're developing and modifying the three.ar.js library itself, there are some helpful build tools for you.

Installing Dependencies

Run npm install to install dependencies required for this project.


Run npm run build to create a new build in ./dist. When sending pull requests, do not build your changes and allow maintainers to do so. There are additional commands for building, like npm run build-min for building the minified file, and npm run build-all for building both.

To auto build when the source changes, run npm run watch.


Run npm run lint to run the linter on code in src/.


Right now, there are only linting tests. To run the tests, execute:

$ npm test

For testing functionality, go through the examples with your changes and ensure the expected functionality.

Releasing a new version

For maintainers, to cut a new release for npm, use the npm version command. The preversion, version and postversion npm scripts will run tests, build, add built files and tag to git, push to github, and publish the new npm version.

npm version <patch|minor|major>

You should be sure that git push pushes to the origin repository if you're working in a fork. See the postversion npm script, and that you have access to both the repo and npm package.


Examples of three.ar.js are in the /examples directory.

A list of examples that are compatible with WebARonARKit and WebARonARCore is also available at developers.google.com.

Created a cool example or want to see more from the community? Check out this gist with some links. Leave a comment to add yours!


Apache License Version 2.0 (see the LICENSE file inside this repo).