Writing a Component

Note: This documentation is for the old 1.1.0 version of A-Frame. Check out the documentation for the current 1.6.0 version

Components of A-Frame’s entity-component framework are JavaScript modules that can be mixed, matched, and composed onto entities to build appearance, behavior, and functionality. We can register component in JavaScript and use it declaratively from the DOM. Components are configurable, reusable, and shareable. Most code in an A-Frame application should live within components.

vehicleimage Image by Ruben Mueller from vrjump.de

This guide will take it pretty slow. We recommend skimming over the Component API documentation before going through this guide as that documentation will be more concise. Note that components should be defined before <a-scene> like:

<html>
  <head>
    <script src="foo-component.js"></script>
  </head>
  <body>
    <script>
      // Or inline before the <a-scene>.
      AFRAME.registerComponent('bar', {
        // ...
      });
    </script>

    <a-scene>
    </a-scene>
  </body>
</html>

We’ll go over examples on writing components. The examples will do mostly trivial things, but will demonstrate data flow, API, and usage. To see examples of non-trivial components, see the Learning Through Components in Ecosystem section.

Example: `hello-world` Component

Let’s start with the most basic component to get a general idea. This component will log a simple message once when the component’s entity is attached using the .init() handler.

Registering the Component with `AFRAME.registerComponent`

Components are registered with AFRAME.registerComponent(). We pass the name of the component, which will be used as the HTML attribute name in the component’s representation in the DOM. Then we pass the component definition which is a JavaScript object of methods and properties. Within the definition, we can define lifecycle handler methods. One of which is .init(), which is called once when the component is first plugged into its entity.

In the example below, we just have our .init() handler log a simple message.

AFRAME.registerComponent('hello-world', {
  init: function () {
    console.log('Hello, World!');
  }
});

Using the Component from HTML

Then we can use our hello-world component declaratively as an HTML attribute.

<a-scene>
  <a-entity hello-world></a-entity>
</a-scene>

Now after the entity is attached and initialized, it will initialize our hello-world component. The wonderful thing about components is that they are called only after the entity is ready. We don’t have to worry about waiting for the scene or entity to set up, it’ll just work! If we check the console, Hello, World! will be logged once after the scene has started running and the entity has attached.

Using the Component from JS

Another way to set a component, rather than via static HTML, is to set it programmatically with .setAttribute(). The scene element can take components too, let’s set our hello-world component on the scene programmatically:

document.querySelector('a-scene').setAttribute('hello-world', '');

Example: `log` Component

Similar to the hello-world component, let’s make a log component. It’ll still only just do console.log, but we’ll make it able to console.log more than just Hello, World!. Our log component will log whatever string its passed in. We’ll find out how to pass data to components by defining configurable properties via the schema.

Defining Properties with the Schema

The schema defines the properties of its component. As an analogy, if we think of a component as a function, then a component’s properties are like its function arguments. A property has a name (if the component has more than one property), a default value, and a property type. Property types define how data is parsed if its passed as a string (i.e., from the DOM).

For our log component, let’s define a message property type via the schema. The message property type will have a string property type and have a default value of Hello, World!:

AFRAME.registerComponent('log', {
  schema: {
    message: {type: 'string', default: 'Hello, World!'}
  },
  // ...
});

Using Property Data from a Lifecycle Handler

The string property type doesn’t do any parsing on the incoming data and will pass it to the lifecycle method handlers as is. Now let’s console.log that message property type. Like the hello-world component, we write a .init() handler, but this time we won’t be logging a hardcoded string. The component’s property type values are available through this.data. So let’s log this.data.message!

AFRAME.registerComponent('log', {
  schema: {
    message: {type: 'string', default: 'Hello, World!'}
  },

  init: function () {
    console.log(this.data.message);
  }
});

Then from HTML, we can attach the component to an entity. For a multi-property component, the syntax is the same as inline css styles (property name/value pairs separated by : and properties separated by ;):

<a-scene>
  <a-entity log="message: Hello, Metaverse!"></a-entity>
</a-scene>

Handling Property Updates

So far, we’ve been using just the .init() handler which is called only once at the beginning of the component lifecycle with only its initial properties. But components often have their properties updated dynamically. We can use the .update() handler to handle property updates.

methodsimage Lifecycle method handlers. Image by Ruben Mueller from vrjump.de

To demonstrate this, we’ll have our log component only log whenever its entity emits an event. First, we’ll add an event property type that specifies which event the component should listen on.

// ...
schema: {
  event: {type: 'string', default: ''},
  message: {type: 'string', default: 'Hello, World!'},
},
// ...

Then we’ll actually move everything from our .init() handler to our .update() handler. The .update() handler is also called right after .init() when the component is attached. Sometimes, we have most of our logic in the .update() handler so we can initialize and handle updates all at once without repeating code.

What we want to do is add an event listener that will listen to the event before logging a message. If the event property type is not specified, we’ll just log the message:

AFRAME.registerComponent('log', {
  schema: {
    event: {type: 'string', default: ''},
    message: {type: 'string', default: 'Hello, World!'}
  },

  update: function () {
    var data = this.data;  // Component property values.
    var el = this.el;  // Reference to the component's entity.

    if (data.event) {
      // This will log the `message` when the entity emits the `event`.
      el.addEventListener(data.event, function () {
        console.log(data.message);
      });
    } else {
      // `event` not specified, just log the message.
      console.log(data.message);
    }
  }
});

Now that we’ve added our event listener property, let’s handle an actual property update. When the event property type changes (e.g., as a result of .setAttribute()), we need to remove the previous event listener, and add a new one.

But to remove an event listener, we need a reference to the function. So let’s first store the function on this.eventHandlerFn whenever we attach an event listener. When we attach properties to the component via this, they’ll be available throughout all the other lifecycle handlers.

AFRAME.registerComponent('log', {
  schema: {
    event: {type: 'string', default: ''},
    message: {type: 'string', default: 'Hello, World!'}
  },

  init: function () {
    // Closure to access fresh `this.data` from event handler context.
    var self = this;

    // .init() is a good place to set up initial state and variables.
    // Store a reference to the handler so we can later remove it.
    this.eventHandlerFn = function () { console.log(self.data.message); };
  },

  update: function () {
    var data = this.data;
    var el = this.el;

    if (data.event) {
      el.addEventListener(data.event, this.eventHandlerFn);
    } else {
      console.log(data.message);
    }
  }
});

Now that we have the event handler function stored. We can remove the event listener whenever the event property type changes. We want to only update the event listener when the event property type changes. We do this by checking this.data against the oldData argument provided by the .update() handler:

AFRAME.registerComponent('log', {
  schema: {
    event: {type: 'string', default: ''},
    message: {type: 'string', default: 'Hello, World!'}
  },

  init: function () {
    var self = this;
    this.eventHandlerFn = function () { console.log(self.data.message); };
  },

  update: function (oldData) {
    var data = this.data;
    var el = this.el;

    // `event` updated. Remove the previous event listener if it exists.
    if (oldData.event && data.event !== oldData.event) {
      el.removeEventListener(oldData.event, this.eventHandlerFn);
    }

    if (data.event) {
      el.addEventListener(data.event, this.eventHandlerFn);
    } else {
      console.log(data.message);
    }
  }
});

Now let’s test our component with an updating event listener. Here’s our scene:

<a-scene>
  <a-entity log="event: anEvent; message: Hello, Metaverse!"></a-entity>
</a-scene>

Let’s have our entity emit the event to test it out:

var el = document.querySelector('a-entity');
el.emit('anEvent');
// >> "Hello, Metaverse!"

Now let’s update our event to test the .update() handler:

var el = document.querySelector('a-entity');
el.setAttribute('log', {event: 'anotherEvent', message: 'Hello, new event!'});
el.emit('anotherEvent');
// >> "Hello, new event!"

Handling Component Removal

Let’s handle the case where the component unplugs from the entity (i.e., .removeAttribute('log')). We can implement the .remove() handler which is called when the component is removed. For the log component, we remove any event listeners the component attached to the entity:

AFRAME.registerComponent('log', {
  schema: {
    event: {type: 'string', default: ''},
    message: {type: 'string', default: 'Hello, World!'}
  },

  init: function () {
    var self = this;
    this.eventHandlerFn = function () { console.log(self.data.message); };
  },

  update: function (oldData) {
    var data = this.data;
    var el = this.el;

    if (oldData.event && data.event !== oldData.event) {
      el.removeEventListener(oldData.event, this.eventHandlerFn);
    }

    if (data.event) {
      el.addEventListener(data.event, this.eventHandlerFn);
    } else {
      console.log(data.message);
    }
  },

  /**
   * Handle component removal.
   */
  remove: function () {
    var data = this.data;
    var el = this.el;

    // Remove event listener.
    if (data.event) {
      el.removeEventListener(data.event, this.eventHandlerFn);
    }
  }
});

Now let’s test out the remove handler. Let’s remove the component and check that emitting the event no longer does anything:

<a-scene>
  <a-entity log="event: anEvent; message: Hello, Metaverse!"></a-entity>
</a-scene>

var el = document.querySelector('a-entity');
el.removeAttribute('log');
el.emit('anEvent');
// >> Nothing should be logged...

Allowing Multiple Instances of a Component

Let’s allow having multiple log components attached to the same entity. To do so, we enable multiple instancing with the .multiple flag. Let’s set that to true:

AFRAME.registerComponent('log', {
  schema: {
    event: {type: 'string', default: ''},
    message: {type: 'string', default: 'Hello, World!'}
  },

  multiple: true,

  // ...
});

The syntax for an attribute name for a multiple-instanced component has the form of <COMPONENTNAME>__<ID>, a double-underscore with an ID suffix. The ID can be whatever we choose. For example, in HTML:

<a-scene>
  <a-entity log__helloworld="message: Hello, World!"
            log__metaverse="message: Hello, Metaverse!"></a-entity>
</a-scene>

Or from JS:

var el = document.querySelector('a-entity');
el.setAttribute('log__helloworld', {message: 'Hello, World!'});
el.setAttribute('log__metaverse', {message: 'Hello, Metaverse!'});

Within the component, if we wanted, we can tell between different instances using this.id and this.attrName. Given log__helloworld, this.id would be helloworld and this.attrName would be the full log__helloworld.

And there we have our basic log component!

Example: `box` Component

For a less trivial example, let’s find out how we can add 3D objects and affect the scene graph by writing a component that uses three.js. To get the idea, we’ll just make a basic box component that creates a box mesh with both geometry and material.

boximage Image by Ruben Mueller from vrjump.de

Note: this is just a 3D equivalent of writing a Hello, World! component. A-Frame provides geometry and material components if we actually wanted to make a box in practice.

Schema and API

Let’s start with the schema. The schema defines the API of your component. We’ll make the width, height, depth, and color configurable through the properties. The width, height, and depth will be number types (i.e., floats) with a default of 1 meter. The color type will have a color type (i.e., a string) with a default of gray:

AFRAME.registerComponent('box', {
  schema: {
    width: {type: 'number', default: 1},
    height: {type: 'number', default: 1},
    depth: {type: 'number', default: 1},
    color: {type: 'color', default: '#AAA'}
  }
});

Later, when we use this component via HTML, the syntax will look like:

<a-scene>
  <a-entity box="width: 0.5; height: 0.25; depth: 1; color: orange"
            position="0 0 -5"></a-entity>
</a-scene>

Creating the Box Mesh

Let’s create our three.js box mesh from the .init(), and we’ll later let the .update() handler handle all the property updates. To create a box in three.js, we’ll create a THREE.BoxBufferGeometry, THREE.MeshStandardMaterial, and finally a THREE.Mesh. Then we set the mesh on our entity to add the mesh to the three.js scene graph using .setObject3D(name, object):

AFRAME.registerComponent('box', {
  schema: {
    width: {type: 'number', default: 1},
    height: {type: 'number', default: 1},
    depth: {type: 'number', default: 1},
    color: {type: 'color', default: '#AAA'}
  },

  /**
   * Initial creation and setting of the mesh.
   */
  init: function () {
    var data = this.data;
    var el = this.el;

    // Create geometry.
    this.geometry = new THREE.BoxBufferGeometry(data.width, data.height, data.depth);

    // Create material.
    this.material = new THREE.MeshStandardMaterial({color: data.color});

    // Create mesh.
    this.mesh = new THREE.Mesh(this.geometry, this.material);

    // Set mesh on entity.
    el.setObject3D('mesh', this.mesh);
  }
});

Now let’s handle updates. If the geometry-related properties (i.e., width, height, depth) update, we’ll just recreate the geometry. If the material-related properties (i.e., color) update, we’ll just update the material in place. To access the mesh to update it, we use .getObject3D('mesh').

AFRAME.registerComponent('box', {
  schema: {
    width: {type: 'number', default: 1},
    height: {type: 'number', default: 1},
    depth: {type: 'number', default: 1},
    color: {type: 'color', default: '#AAA'}
  },

  init: function () {
    var data = this.data;
    var el = this.el;
    this.geometry = new THREE.BoxBufferGeometry(data.width, data.height, data.depth);
    this.material = new THREE.MeshStandardMaterial({color: data.color});
    this.mesh = new THREE.Mesh(this.geometry, this.material);
    el.setObject3D('mesh', this.mesh);
  },

  /**
   * Update the mesh in response to property updates.
   */
  update: function (oldData) {
    var data = this.data;
    var el = this.el;

    // If `oldData` is empty, then this means we're in the initialization process.
    // No need to update.
    if (Object.keys(oldData).length === 0) { return; }

    // Geometry-related properties changed. Update the geometry.
    if (data.width !== oldData.width ||
        data.height !== oldData.height ||
        data.depth !== oldData.depth) {
      el.getObject3D('mesh').geometry = new THREE.BoxBufferGeometry(data.width, data.height,
                                                                    data.depth);
    }

    // Material-related properties changed. Update the material.
    if (data.color !== oldData.color) {
      el.getObject3D('mesh').material.color = new THREE.Color(data.color);
    }
  }
});

Removing the Box Mesh

Lastly, we’ll handle when the component or entity is removed. In this case, we’ll want to remove the mesh from the scene. We can do so with the .remove() handler and .removeObject3D(name):

AFRAME.registerComponent('box', {
  // ...

  remove: function () {
    this.el.removeObject3D('mesh');
  }
});

And that wraps up the basic three.js box component! In practice, a three.js component would do something more useful. Anything that can be accomplished in three.js can be wrapped in an A-Frame component to make it declarative. So check out the three.js features and ecosystem and see what components you can write!

Example: `follow` Component

Let’s write a follow component where we tell one entity to follow another. This will demonstrate the use of the .tick() handler which adds a continuously running behavior that runs on every frame of the render loop to the scene. This will also demonstrate relationships between entities.

Schema and API

First off, we’ll need a target property that specifies which entity to follow. A-Frame has a selector property type to do the trick, allowing us to pass in a query selector and get back an entity element. We’ll also add a speed property (in m/s) to tell specify how fast the entity should follow.

AFRAME.registerComponent('follow', {
  schema: {
    target: {type: 'selector'},
    speed: {type: 'number'}
  }
});

Later, when we use this component via HTML, the syntax will look like:

<a-scene>
  <a-box id="target-box" color="#5E82C5" position="-3 0 -5"></a-box>
  <a-box follow="target: #target-box; speed: 1" color="#FF6B6B" position="3 0 -5"></a-box>
</a-scene>

Creating a Helper Vector

Since the .tick() handler will be called on every frame (e.g., 90 times per second), we want to make sure its performant. One thing we don’t want to do is be creating unnecessary objects on each tick such as THREE.Vector3 objects. That would help lead to garbage collection pauses. Since we’ll need to do some vector operations using a THREE.Vector3, we’ll create it once in the .init() handler so we can later reuse it:

AFRAME.registerComponent('follow', {
  schema: {
    target: {type: 'selector'},
    speed: {type: 'number'}
  },

  init: function () {
    this.directionVec3 = new THREE.Vector3();
  }
});

Defining a Behavior With the `.tick()` Handler

Now we’ll write the .tick() handler so the component continuously moves the entity towards its target at the desired speed. A-Frame passes in the global scene uptime as time and time since the last frame as timeDelta into the tick() handler, in milliseconds. We can use the timeDelta to calculate how far the entity should travel towards the target this frame, given the speed.

To calculate the direction the entity should head in, we subtract the entity’s position vector from the target entity’s direction vector. We have access to the entities’ three.js objects via .object3D, and from there the position vector .position. We store the direction vector in the this.directionVec3 we previously allocated in the init() handler.

Then we factor in the distance to go, the desired speed, and how much time has passed since the last frame to find the appropriate vector to add to the entity’s position. We translate the entity with .setAttribute and in the next frame, the .tick() handler will be run again.

The full .tick() handler is below. .tick() is great because it allows an easy way to hook into the render loop without actually having a reference to the render loop. We just have to define a method. Follow along below with the code comments:

AFRAME.registerComponent('follow', {
  schema: {
    target: {type: 'selector'},
    speed: {type: 'number'}
  },

  init: function () {
    this.directionVec3 = new THREE.Vector3();
  },

  tick: function (time, timeDelta) {
    var directionVec3 = this.directionVec3;

    // Grab position vectors (THREE.Vector3) from the entities' three.js objects.
    var targetPosition = this.data.target.object3D.position;
    var currentPosition = this.el.object3D.position;

    // Subtract the vectors to get the direction the entity should head in.
    directionVec3.copy(targetPosition).sub(currentPosition);

    // Calculate the distance.
    var distance = directionVec3.length();

    // Don't go any closer if a close proximity has been reached.
    if (distance < 1) { return; }

    // Scale the direction vector's magnitude down to match the speed.
    var factor = this.data.speed / distance;
    ['x', 'y', 'z'].forEach(function (axis) {
      directionVec3[axis] *= factor * (timeDelta / 1000);
    });

    // Translate the entity in the direction towards the target.
    this.el.setAttribute('position', {
      x: currentPosition.x + directionVec3.x,
      y: currentPosition.y + directionVec3.y,
      z: currentPosition.z + directionVec3.z
    });
  }
});

Learning Through Components in Ecosystem

There are a large number of components in the ecosystem, most of them open source on GitHub. One way to learn is to browse the source code of other components to see how they’re built and what use cases they provide for. Here are a few places to look:

A-Frame core components - Source code of A-Frame’s standard components.
A-Painter components - Application-specific components for A-Painter.
A Week of A-Frame Weekly Series
Official Site
Community
Components on npm
Twitter

Publishing a Component

Many components in practice will be application-specific or one-off components. But if you wrote a component that could be useful to the community and is generalized enough to work in other applications, you should publish it!

For a component template, we recommend using angle. angle is a command-line interface for A-Frame; one of its features is to set up a component template for publishing to GitHub and npm and also to be consistent with all the other components in the ecosystem. To install the template:

npm install -g angle && angle initcomponent

initcomponent will ask for some information like the component name to get the template set up. Write some code, examples, and documentation, and publish to GitHub and npm!

A-Frame

Writing a Component

Example: hello-world Component

Registering the Component with AFRAME.registerComponent

Using the Component from HTML

Using the Component from JS

Example: log Component

Defining Properties with the Schema

Using Property Data from a Lifecycle Handler

Handling Property Updates

Handling Component Removal

Allowing Multiple Instances of a Component

Example: box Component

Schema and API

Creating the Box Mesh

Removing the Box Mesh

Example: follow Component

Schema and API

Creating a Helper Vector

Defining a Behavior With the .tick() Handler

Learning Through Components in Ecosystem

Publishing a Component

Example: `hello-world` Component

Registering the Component with `AFRAME.registerComponent`

Example: `log` Component

Example: `box` Component

Example: `follow` Component

Defining a Behavior With the `.tick()` Handler