@react-three/fiber
    TypeScript icon, indicating that this package has built-in type declarations

    7.0.6 • Public • Published

    react-three-fiber

    Version Downloads Twitter Discord Open Collective ETH BTC

    react-three-fiber is a React renderer for threejs.

    npm install three @react-three/fiber

    Why?

    Build your scene declaratively with re-usable, self-contained components that react to state, are readily interactive and can tap into React's ecosystem.

    Does it have limitations?

    None. Everything that works in threejs will work here without exception.

    Can it keep up with frequent updates to threejs?

    Yes, because it merely expresses threejs in JSX: <mesh /> becomes new THREE.Mesh(), and that happens dynamically. There is no hard dependency on a particular threejs version, it does not wrap or duplicate a single threejs class.

    Is it slower than plain threejs?

    There is no additional overhead. Components participate in the renderloop outside of React.

    What does it look like?

    Let's make a re-usable component that has its own state, reacts to user-input and participates in the render-loop. (live demo).

    Imports first

    import React, { useRef, useState } from 'react'
    import ReactDOM from 'react-dom'
    import { Canvas, useFrame } from '@react-three/fiber'

    Define a component

    function Box(props) {
      // This reference will give us direct access to the mesh
      const mesh = useRef()
      // Set up state for the hovered and active state
      const [hovered, setHover] = useState(false)
      const [active, setActive] = useState(false)
      // Rotate mesh every frame, this is outside of React without overhead
      useFrame(() => (mesh.current.rotation.x += 0.01))
    
      return (
        <mesh
          {...props}
          ref={mesh}
          scale={active ? 1.5 : 1}
          onClick={(event) => setActive(!active)}
          onPointerOver={(event) => setHover(true)}
          onPointerOut={(event) => setHover(false)}>
          <boxGeometry args={[1, 2, 3]} />
          <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} />
        </mesh>
      )
    }

    Compose the scene

    Either use Canvas, which you can think of as a portal to threejs inside your regular dom graph. Everything within it is a native threejs element. If you want to mix Webgl and Html (react-dom) this is what you should use.

    ReactDOM.render(
      <Canvas>
        <ambientLight />
        <pointLight position={[10, 10, 10]} />
        <Box position={[-1.2, 0, 0]} />
        <Box position={[1.2, 0, 0]} />
      </Canvas>,
      document.getElementById('root'),
    )

    Or use react-three-fibers own render function, which is a little more low-level but could save you the extra cost of carrying react-dom. It renders into a dom canvas element. Use this for Webgl-only apps.

    import { render } from '@react-three/fiber'
    
    render(<Scene />, document.querySelector('canvas'))
    Show TypeScript example
    import { Canvas, MeshProps, useFrame } from '@react-three/fiber'
    
    const Box: React.FC<MeshProps> = (props) => {
      // This reference will give us direct access to the mesh
      const mesh = useRef<THREE.Mesh>(null!)
      // Set up state for the hovered and active state
      const [hovered, setHover] = useState(false)
      const [active, setActive] = useState(false)
      // Rotate mesh every frame, this is outside of React without overhead
      useFrame(() => (mesh.current.rotation.x += 0.01))
    
      return (
        <mesh
          {...props}
          ref={mesh}
          scale={active ? 1.5 : 1}
          onClick={(event) => setActive(!active)}
          onPointerOver={(event) => setHover(true)}
          onPointerOut={(event) => setHover(false)}>
          <boxGeometry args={[1, 2, 3]} />
          <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} />
        </mesh>
      )
    }
    
    ReactDOM.render(
      <Canvas>
        <ambientLight />
        <pointLight position={[10, 10, 10]} />
        <Box position={[-1.2, 0, 0]} />
        <Box position={[1.2, 0, 0]} />
      </Canvas>,
      document.getElementById('root'),
    )

    Documentation

    Fundamentals

    You need to be versed in both React and Threejs before rushing into this. If you are unsure about React consult the official React docs, especially the section about hooks. As for Threejs, make sure you at least glance over the following links:

    1. Make sure you have a basic grasp of Threejs. Keep that site open.
    2. When you know what a scene is, a camera, mesh, geometry, material, fork the demo above.
    3. Look up the JSX elements that you see (mesh, ambientLight, etc), all threejs exports are native to three-fiber.
    4. Try changing some values, scroll though our Api to see what the various settings and hooks do.

    Some reading material:

    Ecosystem

    How to contribute

    If you like this project, please consider helping out. All contributions are welcome as well as donations to Opencollective, or in crypto BTC: 36fuguTPxGCNnYZSRdgdh6Ea94brCAjMbH, ETH: 0x6E3f79Ea1d0dcedeb33D3fC6c34d2B1f156F2682.

    Backers

    Thank you to all our backers! 🙏

    Contributors

    This project exists thanks to all the people who contribute.

    Install

    npm i @react-three/fiber

    DownloadsWeekly Downloads

    14,256

    Version

    7.0.6

    License

    MIT

    Unpacked Size

    236 kB

    Total Files

    20

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar