A growing collection of useful helpers and fully functional, ready-made abstractions for react-three-fiber. If you make a component that is generic enough to be useful to others, think about making it available here through a PR!

npm install @react-three/drei

👉 this package is using the stand-alone three-stdlib instead of three/examples/jsm. 👈

Basic usage:

import { PerspectiveCamera, PositionalAudio, ... } from '@react-three/drei'

React-native:

import { PerspectiveCamera, PositionalAudio, ... } from '@react-three/drei/native'

The native route of the library does not export Html or Loader. The default export of the library is web which does export Html and Loader.

Index

Cameras

PerspectiveCamera

A responsive THREE.PerspectiveCamera that can set itself as the default.

You can also give it children, which will now occupy the same position as the camera and follow along as it moves.

You can also drive it manually, it won't be responsive and you have to calculate aspect ration yourself.

 c.updateProjectionMatrix()}>

OrthographicCamera

A responsive THREE.OrthographicCamera that can set itself as the default.

CubeCamera

A THREE.CubeCamera that returns its texture as a render-prop. It makes children invisible while rendering to the internal buffer so that they are not included in the reflection.

Using the frames prop you can control if this camera renders indefinitively or statically (a given number of times). If you have two static objects in the scene, make it frames={2} for instance, so that both objects get to "see" one another in the reflections, which takes multiple renders. If you have moving objects, unset the prop and use a smaller resolution instead.

  {(texture) => (
    
      
      
    
  )}

Controls

If available controls have damping enabled by default, they manage their own updates, remove themselves on unmount, are compatible with the invalidateFrameloop canvas-flag. They inherit all props from their underlying THREE controls.

Some controls allow you to set makeDefault, similar to, for instance, PerspectiveCamera. This will set react-three-fiber's controls field in the root store. This can make it easier in situations where you want controls to be known and other parts of the app could respond to it. Some drei controls already take it into account, like CameraShake, Gizmo and TransformControls.

Drei currently exports OrbitControls , MapControls , TrackballControls, ArcballControls, FlyControls, DeviceOrientationControls, PointerLockControls , FirstPersonControls

All controls react to the default camera. If you have a in your scene, they will control it. If you need to inject an imperative camera or one that isn't the default, use the `camera` prop:.

PointerLockControls additionally supports a selector prop, which enables the binding of click event handlers for control activation to other elements than document (e.g. a 'Click here to play' button). All elements matching the selector prop will activate the controls.

TransformControls

An abstraction around THREE.TransformControls.

You can wrap objects which then receive a transform gizmo.

You could also reference the object which might make it easier to exchange the target. Now the object does not have to be part of the same sub-graph. References can be plain objects or React.MutableRefObjects.

If you are using other controls (Orbit, Trackball, etc), you will notice how they interfere, dragging one will affect the other. Default-controls will temporarily be disabled automatically when the user is pulling on the transform gizmo.

ScrollControls

Scroll controls create a HTML scroll container in front of the canvas. Everything you drop into the `` component will be affected.

You can listen and react to scroll with the useScroll hook which gives you useful data like the current scroll offset, delta and functions for range finding: range, curve and visible. The latter functions are especially useful if you want to react to the scroll offset, for instance if you wanted to fade things in and out if they are in or out of view.

  {/* You can have components in here, they are not scrolled, but they can still
      react to scroll by using useScroll! */}
  
    
    
    
  
  
    <h1>html in here (optional)</h1>
    <h1 style="{{">second page</h1>
    <h1 style="{{">third page</h1>
  


function Foo(props) {
  const ref = useRef()
  const data = useScroll()
  useFrame(() =&gt; {
    // data.offset = current scroll position, between 0 and 1, dampened
    // data.delta = current delta, between 0 and 1, dampened

    // Will be 0 when the scrollbar is at the starting position,
    // then increase to 1 until 1 / 3 of the scroll distance is reached
    const a = data.range(0, 1 / 3)
    // Will start increasing when 1 / 3 of the scroll distance is reached,
    // and reach 1 when it reaches 2 / 3rds.
    const b = data.range(1 / 3, 1 / 3)
        // Same as above but with a margin of 0.1 on both ends
    const c = data.range(1 / 3, 1 / 3, 0.1)
    // Will move between 0-1-0 for the selected range
    const d = data.curve(1 / 3, 1 / 3)
    // Same as above, but with a margin of 0.1 on both ends
    const d = data.curve(1 / 3, 1 / 3, 0.1)
    // Returns true if the offset is in range and false if it isn't
    const e = data.visible(2 / 3, 1 / 3)
    // The visible function can also receive a margin
    const f = data.visible(2 / 3, 1 / 3, 0.1)
  })
  return 

PresentationControls

Semi-OrbitControls with spring-physics, polar zoom and snap-back, for presentational purposes. These controls do not turn the camera but will spin their contents. They will not suddenly come to rest when they reach limits like OrbitControls do, but rather smoothly anticipate stopping position.

Shapes

Buffer-geometry short-cuts for Plane, Box, Sphere, Circle, Cone, Cylinder, Tube, Torus, TorusKnot, Ring, Tetrahedron, Polyhedron, Icosahedron, Octahedron, Dodecahedron, Extrude, Lathe.

RoundedBox

A box buffer geometry with rounded corners, done with extrusion.

ScreenQuad

A triangle that fills the screen, ideal for full-screen fragment shader work (raymarching, postprocessing). 👉 Why a triangle? 👉 Use as a post processing mesh

Abstractions

Image

A shader-based image component with auto-cover (similar to css/background: cover).

function Foo() {
  const ref = useRef()
  useFrame(() => {
    ref.current.material.zoom = ... // 1 and higher
    ref.current.material.grayscale = ... // between 0 and 1
    ref.current.material.color.set(...) // mix-in color
  })
  return <img>

Text

Hi-quality text rendering w/ signed distance fields (SDF) and antialiasing, using troika-3d-text. All of troikas props are valid! Text is suspense-based!

Line

Renders a THREE.Line2.