rt

react-three

Construct three.js scenes using React

Showing:

Popularity

Downloads/wk

109

Maintenance

No Maintenance Data Available

Package

Dependencies

2

Size (min+gzip)

33.9KB

License

Apache-2.0

Type Definitions

Tree-Shakeable

Yes?

Reviews

Top Feedback

1Great Documentation
1Easy to Use
1Performant
1Bleeding Edge
1Responsive Maintainers

Readme

react-three

Create/control a three.js canvas using React.

To use React for drawing 2D using WebGL, try react-pixi.

If you want a high-performance 3D renderer or automatic managing of resources like geometry and materials then you should look at react-three-renderer. Look here for more details.

You can view an interactive demo (hopefully) at my github demo page. This demo is also available as a standalone project at r3test

Usage

An example render function from the examples:

render: function() {
  var MainCameraElement = React.createElement(
    ReactTHREE.PerspectiveCamera,
    {name:'maincamera', fov:'75', aspect:this.props.width/this.props.height,
     near:1, far:5000,
     position:new THREE.Vector3(0,0,600), lookat:new THREE.Vector3(0,0,0)});

  return React.createElement(
      ReactTHREE.Renderer,
      {width:this.props.width, height:this.props.height},
      React.createElement(
          ReactTHREE.Scene,
          {width:this.props.width, height:this.props.height, camera:'maincamera'},
          MainCameraElement,
          React.createElement(Cupcake, this.props.cupcakedata)
      )
  );
}

or if you want to use JSX,

  render: function() {
    var aspectratio = this.props.width / this.props.height;
    var cameraprops = {fov : 75, aspect : aspectratio, 
                       near : 1, far : 5000, 
                       position : new THREE.Vector3(0,0,600), 
                       lookat : new THREE.Vector3(0,0,0)};

    return <Renderer width={this.props.width} height={this.props.height}>
        <Scene width={this.props.width} height={this.props.height} camera="maincamera">
            <PerspectiveCamera name="maincamera" {...cameraprops} />
            <Cupcake {...this.props.cupcakedata} />
        </Scene>
    </Renderer>;
  }

Install and Use with npm

The current version of react-three is 0.9 which uses React 15.

If you are building a project with a package.json file you can

npm install react --save
npm install react-dom --save
npm install three --save
npm install react-three --save

and then access the extensions via a require expression:

var React = require('react');
var ReactTHREE = require('react-three');
var THREE = require('three');

Building Standalone Files

You can build two versions of the library:

  • The default with global libraries (React,THREE, and ReactTHREE) exposed, for easy inclusion using a <script> tag.
  • The commonjs version which is basically a commonjs module that you can require from.

Checkout the git repository. You will need node and npm.

git clone https://github.com/Izzimach/react-three.git
cd react-three
npm install

At this point, you can build and package the files. If you want a file you can just include using a <script> tag make the default version:

npm run build

This will package up the react-three components along with React and put the result in build/react-three.js. If you include this into your webpage via a script tag:

<script src="react-three.js"></script>

Then the relevant parts will be accessed in the global namespace as React, ReactTHREE, and THREE.

For the commonjs version you must invoke the build-commonjs task:

npm run build-commonjs

This produces the file es5/react-three-commonjs.js which can be used as a normal commonjs library like the one published to npmjs.

Sample Cupcake component

Node Props

In general, you specify props with names and content that are the same as equivalent three.js nodes. For example, the three.js Mesh object has a position, geometry, and material. You would render a Mesh component as:

React.createElement(ReactTHREE.Mesh, {position:p, geometry:g, material:m}

where p,g, and m are the same values you would have set in a three.js Mesh object:

  • p is position, a THREE.Vector3
  • g is geometry data such as THREE.BoxGeometry
  • m is a material like a THREE.MeshBasicMaterial

Extra Props

The THREERenderer component has a few extra props that aren't in the standard Renderer object:

  • enableRapidRender: if set to true will re-render the scene every frame even if nothing was modified by React. This is for handling non-static THREE entities such as animated meshes and particle systems.
  • background: is the background color specified as a number, usually hex (for example 0x202020). This basically maps to the clear color.
  • customRender is a user-defined function that can be used to intercept and modify the render path. It takes arguments (renderer, scene, camera) for each scene. Normal behavior would be to call renderer(scene, camera) but you can do what you want. Be sure to handle the case of multiple scenes!

Also, the THREEScene component has a few extra props that aren't in the standard Scene object:

  • width, height : these are passed into the renderer but also need to be passed in each scene in order to configure the camera.
  • camera: specifies the name of the camera to use when rendering. The default is maincamera
  • orbitControls: you can specify an orbit controller (typically THREE.OrbitControls) for the scene. Note that this consumes mouse input so will not work well with pointerEvents. The 'orbitcontrols' example shows how to use this prop.
  • pointerEvents: an array of strings containing the names of events that will be processed and forwarded to objects in the scene. The code uses ray casting to find which object gets the event. For example ['onClick', 'onMouseMove'] will send mouse clicks and move events to whatever object is under the mouse. To handle events, add handler functions as props to your component with 3D appended - so use the onClick3D prop to handle mouse clicks on your object. See the 'interactive' example for more details.

Examples

Examples are set up in the examples/ directory. You can run

npm run examples

Then open the example index in your browser at http://localhost:8080/

Testing

The test runner requires Firefox to be installed. You can get Firefox from http://firefox.com.

Some tests require WebGL and cannot be run on the CI test server. Because of this, it is recommended that you run the tests locally before submitting a pull request.

You can run two sets of tests via npm: npm run test runs some basic javascript tests while npm run rendertest will check actual rendered output on a WebGL canvas.

npm run test
npm run rendertest

The render tests compare their render output to known correct reference images. If for some reason you need to generate (or regenerate) the pixel reference images, you can! Install slimerjs and run the pixelrefs npm task

npm install -g slimerjs
npm run pixelrefs

Rate & Review

Great Documentation1
Easy to Use1
Performant1
Highly Customizable0
Bleeding Edge1
Responsive Maintainers1
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
Emad Kheir121 Ratings132 Reviews
Full-stack Software Engineer
1 month ago
Great Documentation
Easy to Use
Performant
Bleeding Edge
Responsive Maintainers

I've used this framework twice so far and I'm more than happy to use it on other projects too, it vastly reduces the difficulty of making a 3D scene with WebGL alone and has a React Hooks-based API which makes it feel more tightly integrated with the rest of the code


0

Tutorials

No tutorials found
Add a tutorial