Note: This documentation is for the old 0.5.0 version of A-Frame. Check out the documentation for the current 0.7.0 version
Image by Ruben Mueller from The VR Jump.
Every element in the scene, even elements such as
entities (represented as
<a-entity>). A-Frame modifies the HTML element
prototype to add some extra behavior for certain DOM APIs to tailor them to
A-Frame. See the Entity API documentation for reference on most of
the APIs discussed below.
Components modularize code, make logic and behavior visible from HTML, and
ensure that code at the correct time (e.g., after the scene and entities have
attached and initialized). As the most basic example, to register a
Then to use the component from HTML:
The wonderful thing about the DOM as a scene graph is that the standard DOM
provides utilities for traversal, querying, finding, and selecting through
.querySelectorAll(). Originally inspired by jQuery
selectors, we can learn about query selectors on
Let’s run a few example query selectors. Take the scene below for example.
If we want to grab just one element, we use
.querySelector() which returns
one element. Let’s grab the scene element:
Note if we were working within a component, we’d already have a reference to the scene element without needing to query. All entities have reference to their scene element:
If an element has an ID, we can use an ID selector (i.e.,
#<ID>). Let’s grab
the red box which has an ID. Before we did a query selector on the entire
document. Here, we’ll do a query selector just within the scope of the scene.
With query selectors, we’re able to limit to scope of the query to within any
If we want to grab a group of elements, we use
.querySelectorAll() which returns
an array of elements. We can query across element names:
We can query for elements that have a class with a class selector (i.e.,
.<CLASS_NAME>). Let’s grab every entity that has the
We can query for elements containing an attribute (or in this case, a
component) with an attribute selector (i.e.,
[<ATTRIBUTE_NAME>]). Let’s grab
every entity that has a light:
If we grabbed a group of entities using
.querySelectorAll(), we can loop over
them with a
for loop. Let’s loop over every element in the scene with
To create an entity, we can use
document.createElement. This will give us a
However, this entity will not be initialized or be a part of the scene until we attach it to our scene.
To add an entity to the DOM, we can use
we want to add it to our scene. We grab the scene, create the entity, and
append the entity to our scene.
.appendChild() is an asynchronous operation in the browser. Until
the entity has finished appending to the DOM, we can’t do many operations on
the entity (such as calling
.getAttribute()). If we need to query an
attribute on an entity that has just been appended, we can listen to the
loaded event on the entity, or place logic in an A-Frame component so that
it is executed once it is ready:
To remove an entity from the DOM and thus from the scene, we call
.removeChild(element) from the parent element. If we have an entity, we have to
ask its parent (
parentNode) to remove the entity.
A blank entity doesn’t do anything. We can modify the entity by adding components, configuring component properties, and removing components.
To add a component, we can use
.setAttribute(componentName, data). Let’s add
a geometry component to the entity.
Or adding the community physics component:
Unlike a normal HTML
.setAttribute(), an entity’s
improved to take a variety of types of arguments such as objects, or to be able
to update a single property of a component. Read more about
To update a component, we also use
.setAttribute(). Updating a component
takes several forms.
Let’s update the property of the position component, a single-property component. We can pass either an object or a string. It is slightly preferred to pass an object so A-Frame doesn’t have to parse the string.
Let’s update a single property of the material component, a
multi-property component. We do this by providing the component name, property
name, and then property value to
Let’s update multiple properties at once of the light component, a
multi-property component. We do this by providing the component name and an
object of properties to
.setAttribute(). We’ll change the light’s color and
intensity but leave the type the same:
Let’s replace all the properties of the geometry component, a
multi-property component. We do this by providing the component name, an object
of properties to
.setAttribute(), and a flag that specifies to clobber the
existing properties. We’ll replace all of the geometry’s existing properties with new properties:
To remove or detach a component from an entity, we can use
.removeAttribute(componentName). Let’s remove the default
from the camera entity:
A-Frame elements provide an easy way to emit custom events with
.emit(eventName, eventDetail, bubbles). For example, let’s say we are
building a physics component and we want the entity to send out a signal when
it has collided with another entity:
Then other parts of the code can wait and listen on this event and run code in response. We can pass information and data through the event detail as the second argument. And we can specify whether the event bubbles, meaning that the parent entities will also emit the event. So other parts of the code can register an event listener.
Like with normal HTML elements, we can register an event listener with
.addEventListener(eventName, function). When the event the listener is
registered to is emitted, then the function will be called and handle the
event. For example, continuing from the previous example with the physics
When the entity emits the
physicscollided event, the function will be called
with the event object. Notably in the event object, we have the event detail
which contains data and information passed through the event.
Like with normal HTML elements, when we want to remove the event listener, we
.removeEventListener(eventName, function). We have to pass the same
event name and function that the listener was registered with. For example,
continuing from the previous example with the physics collision event: