A-Frame Web Framework for VR/AR

1.7.1 verified Sun Apr 19 auth: no javascript

A-Frame is an open-source web framework designed for building virtual reality (VR), augmented reality (AR), and general 3D experiences directly within a web browser using declarative HTML. It abstracts away the complexities of WebXR and Three.js, making 3D content creation accessible to a broader audience, including web developers, educators, and artists. The current stable version is 1.7.1, released in April 2025. A-Frame typically releases minor versions every few months, incorporating updates to its underlying Three.js dependency and adding new WebXR features. Key differentiators include its entity-component-system (ECS) architecture, which promotes reusability and modularity, and its focus on performance for interactive WebXR experiences. It supports various platforms, from mobile to desktop and dedicated VR/AR headsets compatible with WebXR.

Common errors

error Uncaught ReferenceError: AFRAME is not defined ↓

cause A-Frame's main script file (aframe.min.js) has not been loaded or has loaded incorrectly before other scripts try to access the global AFRAME object.

fix

Ensure the A-Frame script tag (<script src="https://unpkg.com/aframe/dist/aframe-master.min.js"></script>) is placed correctly in your HTML, preferably in the <head> or at the beginning of <body>, before any custom scripts that use AFRAME.

error Failed to resolve module 'aframe' from ... (or similar bundler error) ↓

cause This error typically occurs in projects using bundlers (like Webpack, Rollup, Parcel) that expect ES Modules, but A-Frame was previously CJS or the bundler configuration is not set up to handle the v1.7.0 ESM transition.

fix

If on A-Frame v1.7.0+, update your bundler configuration to properly resolve ES Modules. Ensure your package.json's type is set to module if it's a pure ESM project, or configure your bundler to handle 'aframe' as an ESM package. Consider using import * as AFRAME from 'aframe';.

error Custom element 'a-scene' has already been defined ↓

cause The A-Frame library, which registers custom HTML elements like `<a-scene>`, has been loaded multiple times on the same page, or another script has inadvertently defined an element with the same tag.

fix

Check your HTML to ensure the A-Frame script is only included once. If using a build system, verify that A-Frame is not being bundled and included multiple times. Avoid manually defining custom elements with a- prefixes if you are using A-Frame.

Warnings

breaking A-Frame v1.7.0 replaced its internal CommonJS module system with ES Modules. Projects relying on `require('aframe')` or specific CommonJS imports for bundlers like Webpack 4 or older Node.js environments will break. ↓

fix Migrate your project to use ES Module `import` syntax. If using a bundler, ensure it is configured for ES Modules (e.g., Webpack 5+). Consider using import maps if targeting modern browsers directly.

breaking A-Frame v1.4.0 migrated its underlying custom element implementation to Custom Elements V1. While largely backward compatible, projects with very specific custom element polyfills or those defining their own custom elements with conflicting naming conventions might experience issues. ↓

fix Ensure your browser or project environment fully supports Custom Elements V1. If you have custom element polyfills, update them to the latest versions. Avoid manually defining custom elements that conflict with A-Frame's `a-` prefixed elements.

breaking A-Frame v1.2.0 updated its bundled Three.js version to r125, which deprecated `THREE.Geometry` in favor of `THREE.BufferGeometry`. Custom components or direct Three.js code that relied on `THREE.Geometry` will likely break. ↓

fix Update any custom A-Frame components or direct Three.js code to use `THREE.BufferGeometry` where applicable. Consult the Three.js migration guides for `r125` for detailed changes.

gotcha When integrating A-Frame with Next.js, versions prior to v1.7.1 could experience issues where A-Frame's default CSS styles were skipped or incorrectly applied, leading to visual glitches or missing UI elements like the 'Enter VR' button. ↓

fix Upgrade A-Frame to v1.7.1 or newer. If upgrading is not immediately possible, consider importing A-Frame's CSS explicitly in your Next.js project, potentially within `_app.js` or via a custom `_document.js`.

Install

npm install aframe

yarn add aframe

pnpm add aframe

Imports

Global AFRAME object via CDN
```

<script src="https://unpkg.com/aframe/dist/aframe-master.min.js"></script>
```
This is the most common way to include A-Frame, making the `AFRAME` global object available. It's suitable for most web projects without complex build setups.
A-Frame as an ES Module
wrong
```
const AFRAME = require('aframe');
```
correct
```
import 'aframe';
// Or if you need the AFRAME object for custom components:
import * as AFRAME from 'aframe';
```
Since v1.7.0, A-Frame officially supports ES Modules. Direct `require()` is no longer supported for modern bundlers without CJS polyfills. When importing without `* as AFRAME`, it initializes A-Frame globally, making `AFRAME` available on `window`.
Registering a custom component
wrong
```
import { registerComponent } from 'aframe'; // Incorrect named import for core functionality
registerComponent('my-component', { /* ... */ });
```
correct
```
AFRAME.registerComponent('my-component', {
  init: function () {
    console.log('My component initialized!');
  }
});
```
Components, systems, and primitives are registered via methods on the global `AFRAME` object, regardless of how A-Frame itself is loaded (CDN or ESM). There are no direct named exports for these core registration functions from the main 'aframe' package.

Quickstart

This quickstart demonstrates a basic A-Frame scene with a camera, a ground, a sky, and a rotating box. It also includes a custom 'rotator' component defined in JavaScript and applied to the box, showcasing A-Frame's extensibility.

<!DOCTYPE html>
<html>
  <head>
    <title>A-Frame Quickstart</title>
    <script src="https://unpkg.com/aframe/dist/aframe-master.min.js"></script>
    <script>
      // Register a custom component
      AFRAME.registerComponent('rotator', {
        schema: { speed: { type: 'number', default: 1000 } },
        init: function () {
          this.el.setAttribute('animation', {
            property: 'rotation',
            to: '0 360 0',
            loop: true,
            dur: this.data.speed
          });
        },
        update: function () {
          this.el.setAttribute('animation', {
            property: 'rotation',
            to: '0 360 0',
            loop: true,
            dur: this.data.speed
          });
        }
      });
    </script>
  </head>
  <body>
    <a-scene background="color: #FAFAFA">
      <!-- Camera with controls -->
      <a-entity camera look-controls wasd-controls position="0 1.6 0"></a-entity>

      <!-- Simple rotating box -->
      <a-box position="0 1 -3" rotation="0 45 0" color="#4CC3D9" rotator="speed: 2000"></a-box>

      <!-- Ground plane -->
      <a-plane position="0 0 -4" rotation="-90 0 0" width="10" height="10" color="#7BC8A4"></a-plane>

      <!-- Sky -->
      <a-sky color="#ECECEC"></a-sky>
    </a-scene>
  </body>
</html>