aframe-react

This is the same package as aframe-react but includes fixes for custom loading components

> I recommend using vanilla A-Frame and aframe-state-component with static templating over aframe-react. React wastes a lot of cycles and incurs a lot of memory garbage. aframe-react is often abused where it is too easy to place 3D/real-time logic at the React layer, causing poor performance (e.g., doing React renders on ticks). aframe-react applications frequently ignore the prescribed ECS framework of A-Frame. Internally, React does tons of computation to compute what changed, and flushes it to the entire application. It is apparent React ecosystem does not care much about memory as most examples allocate functions and objects in the render method, and where immutables are popular. With only ~10ms per frame to do all computation, there is little room for React's massive system.

Build virtual reality experiences with A-Frame and React.

Examples

Fear of the Sky by Amnesty International UK

Installation

Install with npm or
yarn.

``



npm install --save aframe aframe-react react react-dom

yarn add aframe aframe-react react react-dom





Example

js

import "aframe";

import "aframe-particle-system-component";

import { Entity, Scene } from "aframe-react";

import React from "react";

import ReactDOM from "react-dom";



class VRScene extends React.Component {

  render() {

    return (

      

                  geometry={{ primitive: "box" }}

          material={{ color: "red" }}

          position={{ x: 0, y: 0, z: -5 }}

        />

        

        

        

        

      

    );

  }

}



ReactDOM.render(, document.querySelector("#sceneContainer"));





See aframe-react-boilerplate

for a basic example.



Introduction



!A-Frame



A-Frame is a web framework for building virtual reality

experiences. Since A-Frame is built on top of the DOM, web libraries such as

React, Vue.js, Angular, Ember.js, d3.js are able to sit cleanly on top of

A-Frame.



A-Frame is an entity-component-system (ECS) framework exposed through

HTML. ECS is a pattern used in game development that

favors composability over inheritance, which is more naturally suited to 3D

scenes where objects are built of complex appearance, behavior, and

functionality. In A-Frame, HTML attributes map to _components_ which are

composable modules that are plugged into

s to attach appearance,

behavior, and functionality.



Released on the same day as A-Frame,

aframe-react

 is a very thin layer on top

of A-Frame to bridge with React.

aframe-react

 passes React props to directly

A-Frame using refs and

.setAttribute()

, bypassing the DOM. This works since

A-Frame's

.setAttribute()

s are able to take non-string data such as objects,

arrays, or elements and synchronously modify underlying 3D scene graph.

js

// aframe-react's  React Component





// renders





// and then applies the data directly to the underlying 3D scene graph, bypassing the DOM.

.setAttribute('geometry', {primitive: 'box', width: 5});

.setAttribute('position', '0 0 -5');

aframe-react

 provides the best of both worlds between A-Frame and React, the

3D and VR-oriented entity-component architecture of A-Frame, and the view and

state management ergonomics of React, without penalties of attempting to use

React for a VR application.



Making React Viable



A-Frame and

aframe-react

 gives some viability for React to use in VR

applications. The value proposition of React is limited to the 2D Web:



- Improve rendering performance for 2D web pages by reducing calls to the

  browser's 2D layout engine via the virtual DOM.

- Provide an predictable application structure for large 2D web applications through

  a structured nesting of React components, data binding, and one-way data flow.



However, these propositions fall short in 3D and VR applications:



- In 3D and VR applications, including A-Frame, the 2D browser layout engine is

  not touched. Thus React's reconciliation engine can become an unpredictable

  performance liability for little benefit.

- In 3D and VR applications, objects are not structured in a top-down hierarchy like

  2D web applications. 3D objects can exist anywhere and interact with any other 3D object

  in a many-to-many manner. But React's paradigm prescribes data flow from parent-to-child,

  which makes it restrictive for 3D and VR applications.



A-Frame and aframe-react gives meaning and purpose to React: **A-Frame provides

an actual DOM for React to reconcile, diff, and bind to**.



React also raises questions around performance; React is a very large library

designed for a 60fps 2D Web, is it equipped to handle 90fps VR applications?

90 prop updates per second per object for many objects through React's engine

causes concern in the overhead added for each operation.



aframe-react lets A-Frame handle the heavy lifting 3D and VR rendering and

behavior. A-Frame is optimized from the ground up for WebVR with a 3D-oriented

entity-component architecture. And **aframe-react lets React focus on what it's

good at: views, state management, and data binding.**



$3



A-Frame's entity-component-system (ECS) pattern is tailored for 3D and VR

applications. What React did for 2D web applications is what ECS did for 3D

applications in terms of providing a useful abstraction. ECS promotes

composability over hierarchy. In 3D applications, composability refers to

composition of appearance, behavior, and logic rather than having fixed blocks.

This lets us do things like define a flying robot that explodes on contact and

makes robot sounds by snapping together a pre-existing model component, explode

component, event handler component, sound component, and flying component.



Unfortunately, React (and the 2D web for that matter) is heavily hierarchical,

which is not suited for 3D. Whereas 2D web development consisted of structuring

and laying out from an assorted set of fixed 2D elements (e.g.,

, ,,

), 3D development involves objects that are infinite in

complexity and type. ECS provides an easy way of defining those objects by

mixing and matching plug-and-play components.



With aframe-react, we get the best of both worlds. The 3D and VR architecture

of A-Frame, and the view and state ergonomics of React. React can be used to

bind application and state data to the values of A-Frame components. And we

still have access to all the features and performance of A-Frame as well as

A-Frame's community component ecosystem.



API

aframe-react

's API is very thin on top of A-Frame, less than 200 lines of

source code. The API consists of just two React Components:

and

.



#### \

 wraps

, the _entity_

piece of the entity-component-system

pattern. Plug in A-Frame

components

as React props to attach appearance, behavior, or functionality to the

jsx



      geometry={{ primitive: "box", width: 5 }}

    material={{ color: red, roughness: 0.5, src: texture.png }}

    scale={{ x: 2, y: 2, z: 2 }}

    position={{ x: 0, y: 0, z: -5 }}

  />





Community A-Frame components can be imported and

installed through npm:



import 'aframe-particle-system-component';

import 'aframe-mountain-component';



// ...





####

primitive





To use A-Frame primitives, provide

the

primitive prop with the primitive's element name (e.g., a-sphere

).

Mappings can be applied the same as in HTML through React props:

jsx





####

events





To register event handlers, use the

events prop. events

 takes a mapping of

event names to event handler(s). Multiple event handlers can be provided for a

single event name by providing an array of functions. Try not to pass in inline

functions to not trigger unnecessary React renders. Pass in binded functions

instead.



For example, using the synthetic

click event provided by A-Frame's cursor



component, or a

collided

 event possibly provided by a physics component.

jsx

handleClick = () => {

  console.log('Clicked!');

}



handleCollide = () => {

  console.log('Collided!');

}



render() {

  return (

    

              click: this.handleClick,

        collided: [this.handleCollide]}}/>

    

  );

}

aframe-react does not support React-style onXXX

 event handlers (e.g.,

onClick

). Unlike 2D web pages, VR sites are composed entirely of custom

synthetic event names (which could have hyphens, be all lowercase, be

camelCase, all uppercase, camel case, etc.,). The possible event names are

infinite. The

events

 prop makes it explicit what the event names to handle

are.



####

_ref

Use

aframe-react's _ref

 prop to add a callback to the underlying

 DOM node:





#### \

extends and renders

instead of

.

Place all

s as a child of the

 Component. There should

only be one

 per page:

jsx





Best Practices



Let A-Frame and three.js handle the heavy lifting of 3D rendering and behavior,

and delegate React to what it was meant for: views, state management, and data

binding.



For example, don't create

requestAnimationFrame

s to continuously throw React

prop updates to A-Frame. Instead, create an A-Frame component with a tick

handler such that everything is done in memory with little overhead. Do however

use React to set up initial state and data binding that might configure that

A-Frame component.



Using with Preact

aframe-react works with Preact. Since aframe-react uses React.Component

,

we have to tell Webpack to alias that to

Preact.Component



resolve: {

  alias: {

    react: 'preact'

  }

}

Installation

npm

yarn

npm install --save aframe aframe-react react react-dom
yarn add aframe aframe-react react react-dom

Example

js
import "aframe";
import "aframe-particle-system-component";
import { Entity, Scene } from "aframe-react";
import React from "react";
import ReactDOM from "react-dom";

class VRScene extends React.Component {
render() {
return (

geometry={{ primitive: "box" }}
material={{ color: "red" }}
position={{ x: 0, y: 0, z: -5 }}
/>

);
}
}

ReactDOM.render(, document.querySelector("#sceneContainer"));

See aframe-react-boilerplate
for a basic example.

Introduction

!A-Frame

A-Frame is a web framework for building virtual reality
experiences. Since A-Frame is built on top of the DOM, web libraries such as
React, Vue.js, Angular, Ember.js, d3.js are able to sit cleanly on top of
A-Frame.

A-Frame is an entity-component-system (ECS) framework exposed through
HTML. ECS is a pattern used in game development that
favors composability over inheritance, which is more naturally suited to 3D
scenes where objects are built of complex appearance, behavior, and
functionality. In A-Frame, HTML attributes map to _components_ which are
composable modules that are plugged into

s to attach appearance,

behavior, and functionality.



Released on the same day as A-Frame,

aframe-react

 is a very thin layer on top

of A-Frame to bridge with React.

aframe-react

 passes React props to directly

A-Frame using refs and

.setAttribute()

, bypassing the DOM. This works since

A-Frame's

.setAttribute()

s are able to take non-string data such as objects,

arrays, or elements and synchronously modify underlying 3D scene graph.

js

// aframe-react's  React Component





// renders





// and then applies the data directly to the underlying 3D scene graph, bypassing the DOM.

.setAttribute('geometry', {primitive: 'box', width: 5});

.setAttribute('position', '0 0 -5');

aframe-react

 provides the best of both worlds between A-Frame and React, the

3D and VR-oriented entity-component architecture of A-Frame, and the view and

state management ergonomics of React, without penalties of attempting to use

React for a VR application.



Making React Viable



A-Frame and

aframe-react

 gives some viability for React to use in VR

applications. The value proposition of React is limited to the 2D Web:



- Improve rendering performance for 2D web pages by reducing calls to the

  browser's 2D layout engine via the virtual DOM.

- Provide an predictable application structure for large 2D web applications through

  a structured nesting of React components, data binding, and one-way data flow.



However, these propositions fall short in 3D and VR applications:



- In 3D and VR applications, including A-Frame, the 2D browser layout engine is

  not touched. Thus React's reconciliation engine can become an unpredictable

  performance liability for little benefit.

- In 3D and VR applications, objects are not structured in a top-down hierarchy like

  2D web applications. 3D objects can exist anywhere and interact with any other 3D object

  in a many-to-many manner. But React's paradigm prescribes data flow from parent-to-child,

  which makes it restrictive for 3D and VR applications.



A-Frame and aframe-react gives meaning and purpose to React: **A-Frame provides

an actual DOM for React to reconcile, diff, and bind to**.



React also raises questions around performance; React is a very large library

designed for a 60fps 2D Web, is it equipped to handle 90fps VR applications?

90 prop updates per second per object for many objects through React's engine

causes concern in the overhead added for each operation.



aframe-react lets A-Frame handle the heavy lifting 3D and VR rendering and

behavior. A-Frame is optimized from the ground up for WebVR with a 3D-oriented

entity-component architecture. And **aframe-react lets React focus on what it's

good at: views, state management, and data binding.**



$3



A-Frame's entity-component-system (ECS) pattern is tailored for 3D and VR

applications. What React did for 2D web applications is what ECS did for 3D

applications in terms of providing a useful abstraction. ECS promotes

composability over hierarchy. In 3D applications, composability refers to

composition of appearance, behavior, and logic rather than having fixed blocks.

This lets us do things like define a flying robot that explodes on contact and

makes robot sounds by snapping together a pre-existing model component, explode

component, event handler component, sound component, and flying component.



Unfortunately, React (and the 2D web for that matter) is heavily hierarchical,

which is not suited for 3D. Whereas 2D web development consisted of structuring

and laying out from an assorted set of fixed 2D elements (e.g.,

, ,, ), 3D development involves objects that are infinite in complexity and type. ECS provides an easy way of defining those objects by mixing and matching plug-and-play components. With aframe-react, we get the best of both worlds. The 3D and VR architecture of A-Frame, and the view and state ergonomics of React. React can be used to bind application and state data to the values of A-Frame components. And we still have access to all the features and performance of A-Frame as well asA-Frame's community component ecosystem.

`API`

aframe-react

's API is very thin on top of A-Frame, less than 200 lines of

source code. The API consists of just two React Components:

and

.



#### \

 wraps

, the _entity_

piece of the entity-component-system

pattern. Plug in A-Frame

components

as React props to attach appearance, behavior, or functionality to the

jsx



      geometry={{ primitive: "box", width: 5 }}

    material={{ color: red, roughness: 0.5, src: texture.png }}

    scale={{ x: 2, y: 2, z: 2 }}

    position={{ x: 0, y: 0, z: -5 }}

  />





Community A-Frame components can be imported and

installed through npm:



import 'aframe-particle-system-component';

import 'aframe-mountain-component';



// ...





####

primitive





To use A-Frame primitives, provide

the

primitive prop with the primitive's element name (e.g., a-sphere

).

Mappings can be applied the same as in HTML through React props:

jsx





####

events





To register event handlers, use the

events prop. events

 takes a mapping of

event names to event handler(s). Multiple event handlers can be provided for a

single event name by providing an array of functions. Try not to pass in inline

functions to not trigger unnecessary React renders. Pass in binded functions

instead.



For example, using the synthetic

click event provided by A-Frame's cursor



component, or a

collided

 event possibly provided by a physics component.

jsx

handleClick = () => {

  console.log('Clicked!');

}



handleCollide = () => {

  console.log('Collided!');

}



render() {

  return (

    

              click: this.handleClick,

        collided: [this.handleCollide]}}/>

    

  );

}

aframe-react does not support React-style onXXX

 event handlers (e.g.,

onClick

). Unlike 2D web pages, VR sites are composed entirely of custom

synthetic event names (which could have hyphens, be all lowercase, be

camelCase, all uppercase, camel case, etc.,). The possible event names are

infinite. The

events

 prop makes it explicit what the event names to handle

are.



####

_ref

Use

aframe-react's _ref

 prop to add a callback to the underlying

 DOM node:





#### \

extends and renders

instead of

.

Place all

s as a child of the

 Component. There should

only be one

 per page:

jsx





Best Practices



Let A-Frame and three.js handle the heavy lifting of 3D rendering and behavior,

and delegate React to what it was meant for: views, state management, and data

binding.



For example, don't create

requestAnimationFrame

s to continuously throw React

prop updates to A-Frame. Instead, create an A-Frame component with a tick

handler such that everything is done in memory with little overhead. Do however

use React to set up initial state and data binding that might configure that

A-Frame component.



Using with Preact

aframe-react works with Preact. Since aframe-react uses React.Component

,

we have to tell Webpack to alias that to

Preact.Component



resolve: {

  alias: {

    react: 'preact'

  }

}

aframe-react-custom

aframe-react

Build virtual reality experiences with A-Frame and React.

Examples

Installation

Example

Introduction

Making React Viable

$3

API

Best Practices

Using with Preact

aframe-react-custom

aframe-react

Build virtual reality experiences with A-Frame and React.

Examples

Installation

Example

Introduction

Making React Viable

$3

`API`

Best Practices

Using with Preact