HTML & Primitives

This section will go over the concepts of A-Frame’s primitive elements and
their relation to the entity-component framework. If you’re looking for a guide
on using HTML and primitives, check out the Building a Basic Scene
guide.

HTML

A-Frame is based on top of HTML and the DOM using a polyfill for
Custom Elements. HTML is the building block of the Web, providing one of the
most accessible computing languages around. There are no installations or build
steps required, creating with HTML involves just text in an HTML file and
opening the HTML file in a browser. Since most of the Web was built on top of
HTML, most existing tools and libraries work with A-Frame including React,
Vue.js, Angular, d3.js, and jQuery.

)

If you don’t have too much experience with HTML, no problem! It’s fairly easy
to pick up and perhaps even easier to grasp than 2D HTML. Once you pick up the
general structure or syntax of HTML (opening tag, attributes, closing tag),
then you’re good to go! Read an introduction to HTML on MDN.

Primitives

While the HTML layer looks basic, HTML and the DOM are only the outermost
abstraction layer of A-Frame. Underneath, A-Frame is an entity-component
framework for three.js that is exposed declaratively.

A-Frame provides a handful of elements such as <a-box> or <a-sky> called
primitives that wrap the entity-component pattern to make it appealing for
beginners. At the bottom of the documentation navigation sidebar, we can see
every primitive that A-Frame provides out of the box. Developers can create
their own primitives as well.

Example

Below is the Hello, WebVR example that uses a few basic primitives. A-Frame
provides primitives to create meshes, render 360° content, customize the
environment, place the camera, etc.

<a-box> defaults the geometry.primitive property to box. And the
primitive maps the HTML width attribute to the underlying geometry.width
property as well as the HTML color attribute to the underlying
material.color property.

Attaching Components to Primitives

Primitives are just <a-entity>s under the hood. This means primitives have
the same API as entities such as positioning, rotating, scaling, and attaching
components.

Registering a Primitive

We can register our own primitives (i.e., register an element) using
AFRAME.registerPrimitive(name, definition). name is a string and must contain a dash (i.e. 'a-foo'). definition is a JavaScript
object defining these properties:

Property

Description

Example

defaultComponents

Object specifying default components of the primitive. The keys are the components’ names and the values are the components’ default data.

{geometry: {primitive: 'box'}}

mappings

Object specifying mapping between HTML attribute name and component property names. Whenever the HTML attribute name is updated, the primitive will update the corresponding component property. The component property is defined using a dot syntax ${componentName}.${propertyName}.