@react-three/drei 9.0.0-beta.1 → 9.0.0-beta.4

package/README.md

@@ -65,6 +65,10 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#effects">Effects</a></li>
           <li><a href="#gradienttexture">GradientTexture</a></li>
           <li><a href="#edges">Edges</a></li>
+          <li><a href="#trail">Trail</a></li>
+          <li><a href="#sampler">Sampler</a></li>
+          <li><a href="#computedattribute">Computed Attribute</a></li>
+          <li><a href="#clone">Clone</a></li>
           <li><a href="#useanimations">useAnimations</a></li>
         </ul>
         <li><a href="#shaders">Shaders</a></li>
@@ -99,6 +103,8 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#useaspect">useAspect</a></li>
           <li><a href="#usecursor">useCursor</a></li>
           <li><a href="#useintersect">useIntersect</a></li>
+          <li><a href="#useboxprojectedenv">useBoxProjectedEnv</a></li>
+          <li><a href="#useTrail">useTrail</a></li>
         </ul>
         <li><a href="#loading">Loaders</a></li>
         <ul>
@@ -159,6 +165,7 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#stage">Stage</a></li>
           <li><a href="#backdrop">Backdrop</a></li>
           <li><a href="#environment">Environment</a></li>
+          <li><a href="#lightformer">Lightformer</a></li>
           <li><a href="#spotlight">SpotLight</a></li>
           <li><a href="#shadow">Shadow</a></li>
           <li><a href="#contactshadows">ContactShadows</a></li>
@@ -243,12 +250,16 @@ Drei currently exports OrbitControls [![](https://img.shields.io/badge/-storyboo
 
 All controls react to the default camera. If you have a `<PerspectiveCamera makeDefault />` 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: `<OrbitControls camera={MyCamera} />`.
 
-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.
+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. It will also center raycast events by default, so regular onPointerOver/etc events on meshes will continue to work.
 
 # TransformControls
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/controls-transformcontrols--transform-controls-story)
 
+<p>
+  <a href="https://codesandbox.io/s/btsbj"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/btsbj/screenshot.png" alt="Tranform controls"/></a>
+</p>
+
 An abstraction around [THREE.TransformControls](https://threejs.org/docs/#examples/en/controls/TransformControls).
 
 You can wrap objects which then receive a transform gizmo.
@@ -277,13 +288,13 @@ If you are using other controls (Orbit, Trackball, etc), you will notice how the
 
 ![](https://img.shields.io/badge/-Dom only-red)
 
-<p align="center">
-  <a href="https://codesandbox.io/s/l4klb"><img width="16%" src="https://codesandbox.io/api/v1/sandboxes/l4klb/screenshot.png" alt="Horizontal tiles"/></a>
-  <a href="https://codesandbox.io/s/4m0d0"><img width="16%" src="https://codesandbox.io/api/v1/sandboxes/4m0d0/screenshot.png" alt="M1 scroll"/></a>
-  <a href="https://codesandbox.io/s/gsm1y"><img width="16%" src="https://codesandbox.io/api/v1/sandboxes/gsm1y/screenshot.png" alt="useIntersect"/></a>
-  <a href="https://codesandbox.io/s/x8gvs"><img width="16%" src="https://codesandbox.io/api/v1/sandboxes/x8gvs/screenshot.png" alt="Infinite scroll"/></a>
-  <a href="https://codesandbox.io/s/yjhzv"><img width="16%" src="https://codesandbox.io/api/v1/sandboxes/yjhzv/screenshot.png" alt="Vertical scroll"/></a>
-  <a href="https://codesandbox.io/s/4jr4p"><img width="16%" src="https://codesandbox.io/api/v1/sandboxes/4jr4p/screenshot.png" alt="GLTF and useScroll"/></a>
+<p>
+  <a href="https://codesandbox.io/s/l4klb"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/l4klb/screenshot.png" alt="Horizontal tiles"/></a>
+  <a href="https://codesandbox.io/s/4m0d0"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/4m0d0/screenshot.png" alt="M1 scroll"/></a>
+  <a href="https://codesandbox.io/s/gsm1y"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/gsm1y/screenshot.png" alt="useIntersect"/></a>
+  <a href="https://codesandbox.io/s/x8gvs"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/x8gvs/screenshot.png" alt="Infinite scroll"/></a>
+  <a href="https://codesandbox.io/s/yjhzv"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/yjhzv/screenshot.png" alt="Vertical scroll"/></a>
+  <a href="https://codesandbox.io/s/4jr4p"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/4jr4p/screenshot.png" alt="GLTF and useScroll"/></a>
 </p>
 
 Scroll controls create a HTML scroll container in front of the canvas. Everything you drop into the `<Scroll>` component will be affected.
@@ -343,6 +354,11 @@ function Foo(props) {
 
 ![](https://img.shields.io/badge/-Dom only-red)
 
+<p>
+  <a href="https://codesandbox.io/s/kheke"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/kheke/screenshot.png" alt="Journey stage 1"/></a>
+  <a href="https://codesandbox.io/s/qyz5r"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/qyz5r/screenshot.png" alt="Watch"/></a>
+</p>
+
 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.
 
 ```jsx
@@ -355,7 +371,7 @@ Semi-OrbitControls with spring-physics, polar zoom and snap-back, for presentati
   rotation={[0, 0, 0]} // Default rotation
   polar={[0, Math.PI / 2]} // Vertical limits
   azimuth={[-Infinity, Infinity]} // Horizontal limits
-  config = { mass: 1, tension: 170, friction: 26 } // Spring config
+  config={{ mass: 1, tension: 170, friction: 26 }} // Spring config
 >
   <mesh />
 </PresentationControls>
@@ -398,6 +414,13 @@ A triangle that fills the screen, ideal for full-screen fragment shader work (ra
 
 #### Image
 
+<p>
+  <a href="https://codesandbox.io/s/l4klb"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/l4klb/screenshot.png" alt="Horizontal tiles"/></a>
+  <a href="https://codesandbox.io/s/gsm1y"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/gsm1y/screenshot.png" alt="useIntersect"/></a>
+  <a href="https://codesandbox.io/s/x8gvs"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/x8gvs/screenshot.png" alt="Infinite scroll"/></a>
+  <a href="https://codesandbox.io/s/yjhzv"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/yjhzv/screenshot.png" alt="Vertical scroll"/></a>
+</p>
+
 A shader-based image component with auto-cover (similar to css/background: cover).
 
 ```jsx
@@ -413,9 +436,13 @@ function Foo() {
 
 #### Text
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-text--text-st)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-text--text-st) ![](https://img.shields.io/badge/-suspense-brightgreen)
 
-Hi-quality text rendering w/ signed distance fields (SDF) and antialiasing, using [troika-3d-text](https://github.com/protectwise/troika/tree/master/packages/troika-3d-text). All of troikas props are valid!
+<p>
+  <a href="https://codesandbox.io/s/yup2o"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/yup2o/screenshot.png" alt="Demo"/></a>
+</p>
+
+Hi-quality text rendering w/ signed distance fields (SDF) and antialiasing, using [troika-3d-text](https://github.com/protectwise/troika/tree/master/packages/troika-3d-text). All of troikas props are valid! Text is suspense-based!
 
 ```jsx
 <Text color="black" anchorX="center" anchorY="middle">
@@ -423,6 +450,14 @@ Hi-quality text rendering w/ signed distance fields (SDF) and antialiasing, usin
 </Text>
 ```
 
+Text will suspend while loading the font data, but in order to completely avoid FOUC you can pass the characters it needs to render.
+
+```jsx
+<Text font={fontUrl} characters="abcdefghijklmnopqrstuvwxyz0123456789!">
+  hello world!
+</Text>
+```
+
 #### Line
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-line--basic-line)
@@ -445,6 +480,10 @@ Renders a THREE.Line2.
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-line--quadratic-bezier)
 
+<p>
+  <a href="https://codesandbox.io/s/2ij9u"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/2ij9u/screenshot.png" alt="Demo"/></a>
+</p>
+
 Renders a THREE.Line2 using THREE.QuadraticBezierCurve3 for interpolation.
 
 ```jsx
@@ -499,6 +538,10 @@ Renders a THREE.Line2 using THREE.CubicBezierCurve3 for interpolation.
 
 #### PositionalAudio
 
+<p>
+  <a href="https://codesandbox.io/s/gkfhr"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/gkfhr/screenshot.png" alt="Demo"/></a>
+</p>
+
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-positionalaudio--positional-audio-scene-st) ![](https://img.shields.io/badge/-suspense-brightgreen)
 
 A wrapper around [THREE.PositionalAudio](https://threejs.org/docs/#api/en/audio/PositionalAudio). Add this to groups or meshes to tie them to a sound that plays when the camera comes near.
@@ -531,7 +574,7 @@ Adds a `<group />` that always faces the camera.
 
 #### GizmoHelper
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/gizmos-gizmohelper--default-story)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/gizmos-gizmohelper--gizmo-helper-story)
 
 Used by widgets that visualize and control camera position.
 
@@ -564,12 +607,16 @@ Abstraction around threes own [EffectComposer](https://threejs.org/docs/#example
 
 #### GradientTexture
 
+<p>
+  <a href="https://codesandbox.io/s/l03yb"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/l03yb/screenshot.png" alt="Demo"/></a>
+</p>
+
 A declarative THREE.Texture which attaches to "map" by default. You can use this to create gradient backgrounds.
 
 ```jsx
 <mesh>
   <planeGeometry />
-  <meshBasicMaterial depthWrite={false}>
+  <meshBasicMaterial>
     <GradientTexture
       stops={[0, 1]} // As many stops as you want
       colors={['aquamarine', 'hotpink']} // Colors need to match the number of stops
@@ -581,6 +628,10 @@ A declarative THREE.Texture which attaches to "map" by default. You can use this
 
 #### Edges
 
+<p>
+  <a href="https://codesandbox.io/s/ny3p4"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/ny3p4/screenshot.png" alt="Demo"/></a>
+</p>
+
 Abstracts [THREE.EdgesGeometry](https://threejs.org/docs/#api/en/geometries/EdgesGeometry). It pulls the geometry automatically from its parent, optionally you can ungroup it and give it a `geometry` prop. You can give it children, for instance a custom material.
 
 ```jsx
@@ -595,10 +646,174 @@ Abstracts [THREE.EdgesGeometry](https://threejs.org/docs/#api/en/geometries/Edge
 </mesh>
 ```
 
+#### Trail
+
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-trail--use-trail-st)
+
+A declarative, `three.MeshLine` based Trails implementation. You can attach it to any mesh and it will give it a beautiful trail.
+
+Props defined bellow with their default values.
+
+```jsx
+<Trail
+  width={0.2} // Width of the line
+  color={'hotpink'} // Color of the line
+  length={1} // Length of the line
+  decay={1} // How fast the line fades away
+  local={false} // Wether to use the target's world or local positions
+  stride={0} // Min distance between previous and current point
+  interval={1} // Number of frames to wait before next calculation
+  target={undefined} // Optional target. This object will produce the trail.
+  attenuation={(width) => width} // A function to define the width in each point along it.
+>
+  {/* If `target` is not defined, Trail will use the first `Object3D` child as the target. */}
+  <mesh>
+    <sphereGeometry />
+    <meshBasicMaterial />
+  </mesh>
+
+  {/* You can optionally define a custom meshLineMaterial to use. */}
+  {/* <meshLineMaterial color={"red"} /> */}
+</Trail>
+```
+
+👉 Inspired by [TheSpite's Codevember 2021 #9](https://spite.github.io/codevember-2021/9/)
+
+#### Sampler
+
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-sampler--sampler-st)
+
+<p>
+  <a href="https://codesandbox.io/s/ehflx3">
+    <img width="20%" src="https://codesandbox.io/api/v1/sandboxes/ehflx3/screenshot.png" alt="Demo"/>
+  </a> <br />
+  <small>– <a href="https://codesandbox.io/s/ehflx3">Complex Demo</a> by <a href="https://twitter.com/CantBeFaraz">@CantBeFaraz</a></small> <br />
+  <small>– <a href="https://codesandbox.io/s/k6rcp2">Simple Demo</a> by <a href="https://twitter.com/ggsimm">@ggsimm</a></small>
+</p>
+
+Declarative abstraction around MeshSurfaceSampler & InstancedMesh.
+It samples points from the passed mesh and transforms an InstancedMesh's matrix to distribute instances on the points.
+
+Check the demos & code for more.
+
+You can either pass a Mesh and InstancedMesh as children:
+
+```tsx
+// This simple example scatters 1000 spheres on the surface of the sphere mesh.
+<Sampler
+  weight={"normal"} // the name of the attribute to be used as sampling weight
+  transform={transformPoint} // a function that transforms each instance given a sample. See the examples for more.
+>
+  <mesh>
+    <sphereGeometry args={[2]} />
+  </mesh>
+
+  <instancedMesh args={[null, null, 1_000]}>
+    <sphereGeometry args={[0.1]}>
+  </instancedMesh>
+</Sampler>
+```
+
+or use refs when you can't compose declaratively:
+
+```tsx
+const { nodes } = useGLTF('my/mesh/url')
+const mesh = useRef(nodes)
+const instances = useRef()
+
+return <>
+  <instancedMesh args={[null, null, 1_000]}>
+    <sphereGeometry args={[0.1]}>
+  </instancedMesh>
+
+  <Sampler mesh={mesh} instances={instances}>
+</>
+```
+
+#### ComputedAttribute
+
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-sampler--sampler-weight-st)
+
+Create and attach an attribute declaratively.
+
+```tsx
+<sphereGeometry>
+  <ComputedAttribute
+    // attribute will be added to the geometry with this name
+    name="my-attribute-name"
+    compute={(geometry) => {
+      // ...someLogic;
+      return new THREE.BufferAttribute([1, 2, 3], 1)
+    }}
+    // you can pass any BufferAttribute prop to this component, eg.
+    usage={THREE.StaticReadUsage}
+  />
+</sphereGeometry>
+```
+
+#### Clone
+
+<p>
+  <a href="https://codesandbox.io/s/42glz0"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/42glz0/screenshot.png" alt="Demo"/></a>
+</p>
+
+Declarative abstraction around THREE.Object3D.clone. This is useful when you want to create a shallow copy of an existing fragment (and Object3D, Groups, etc) into your scene, for instance a group from a loaded GLTF. This clone is now re-usable, but it will still refer to the original geometries and materials.
+
+```ts
+<Clone
+  /** Any pre-existing THREE.Object3D (groups, meshes, ...), or an array of objects */
+  object: THREE.Object3D | THREE.Object3D[]
+  /** Children will be placed within the object, or within the group that holds arrayed objects */
+  children?: React.ReactNode
+  /** Can clone materials and/or geometries deeply (default: false) */
+  deep?: boolean | 'materialsOnly' | 'geometriesOnly'
+  /** The property keys it will shallow-clone (material, geometry, visible, ...) */
+  keys?: string[]
+  /** Can either spread over props or fill in JSX children, applies to every mesh within */
+  inject?: MeshProps | React.ReactNode | ((object: THREE.Object3D) => React.ReactNode)
+  /** Short access castShadow, applied to every mesh within */
+  castShadow?: boolean
+  /** Short access receiveShadow, applied to every mesh within */
+  receiveShadow?: boolean
+/>
+```
+
+You create a shallow clone by passing a pre-existing object to the `object` prop.
+
+```jsx
+const { nodes } = useGLTF(url)
+return (
+  <Clone object={nodes.table} />
+```
+
+Or, multiple objects:
+
+```jsx
+<Clone object={[nodes.foo, nodes.bar]} />
+```
+
+You can dynamically insert objects, these will apply to anything that isn't a group or a plain object3d (meshes, lines, etc):
+
+```jsx
+<Clone object={nodes.table} inject={<meshStandardMaterial color="green" />} />
+```
+
+Or make inserts conditional:
+
+```jsx
+<Clone object={nodes.table} inject={
+  {(object) => (object.name === 'table' ? <meshStandardMaterial color="green" /> : null)}
+} />
+```
+
 #### useAnimations
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/abstractions-useanimations--use-animations-st)
 
+<p>
+  <a href="https://codesandbox.io/s/pecl6"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/pecl6/screenshot.png" alt="Demo"/></a>
+</p>
+
 A hook that abstracts [AnimationMixer](https://threejs.org/docs/#api/en/animation/AnimationMixer).
 
 ```jsx
@@ -625,6 +840,11 @@ return <primitive object={scene} />
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/shaders-meshreflectormaterial--reflector-st)
 
+<p>
+  <a href="https://codesandbox.io/s/lx2h8"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/lx2h8/screenshot.png" alt="Demo"/></a>
+  <a href="https://codesandbox.io/s/l900i"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/l900i/screenshot.png" alt="Demo"/></a>
+</p>
+
 Easily add reflections and/or blur to any mesh. It takes surface roughness into account for a more realistic effect. This material extends from [THREE.MeshStandardMaterial](https://threejs.org/docs/#api/en/materials/MeshStandardMaterial) and accepts all its props.
 
 ```jsx
@@ -650,6 +870,7 @@ Easily add reflections and/or blur to any mesh. It takes surface roughness into
       3 = distortion channel
       4 = lod channel (based on the roughness)
     */
+   reflectorOffset={0.2} // Offsets the virtual camera that projects the reflection. Useful when the reflective surface is some distance from the object's origin (default = 0)
   >
 </mesh>
 ```
@@ -671,6 +892,10 @@ This material makes your geometry wobble and wave around. It was taken from the
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/shaders-meshdistortmaterial--mesh-distort-material-st)
 
+<p>
+  <a href="https://codesandbox.io/s/l03yb"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/l03yb/screenshot.png" alt="Demo"/></a>
+</p>
+
 This material makes your geometry distort following simplex noise.
 
 ```jsx
@@ -682,7 +907,7 @@ This material makes your geometry distort following simplex noise.
 
 #### PointMaterial
 
-An antialiased round dot that always keeps the same size.
+Antialiased round dots. It takes the same props as regular THREE.PointsMaterial
 
 ```jsx
 <points>
@@ -694,6 +919,10 @@ An antialiased round dot that always keeps the same size.
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/shaders-softshadows--soft-shadows-st)
 
+<p>
+  <a href="https://codesandbox.io/s/dh2jc"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/dh2jc/screenshot.png" alt="Demo"/></a>
+</p>
+
 Injects [percent closer soft shadows (pcss)](https://threejs.org/examples/#webgl_shadowmap_pcss) into threes shader chunk.
 
 ```jsx
@@ -710,6 +939,10 @@ softShadows({
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/shaders-shadermaterial--shader-material-story)
 
+<p>
+  <a href="https://codesandbox.io/s/ni6v4"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/ni6v4/screenshot.png" alt="Demo"/></a>
+</p>
+
 Creates a THREE.ShaderMaterial for you with easier handling of uniforms, which are also automatically declared as setter/getters on the object.
 
 ```jsx
@@ -804,6 +1037,12 @@ function Scene() {
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-html--html-st) ![](https://img.shields.io/badge/-Dom only-red)
 
+<p>
+  <a href="https://codesandbox.io/s/qyz5r"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/qyz5r/screenshot.png" alt="Demo"/></a>
+  <a href="https://codesandbox.io/s/9keg6"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/9keg6/screenshot.png" alt="Demo"/></a>
+  <a href="https://codesandbox.io/s/6oei7"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/6oei7/screenshot.png" alt="Demo"/></a>
+</p>
+
 Allows you to tie HTML content to any object of your scene. It will be projected to the objects whereabouts automatically.
 
 ```jsx
@@ -857,6 +1096,10 @@ const [hidden, set] = useState()
 
 ![](https://img.shields.io/badge/-Dom only-red)
 
+<p>
+  <a href="https://codesandbox.io/s/ls503"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/ls503/screenshot.png" alt="Demo"/></a>
+</p>
+
 This component allows you to cycle through all objects underneath the cursor with optional visual feedback. This can be useful for non-trivial selection, CAD data, housing, everything that has layers. It does this by changing the raycasters filter function and then refreshing the raycaster.
 
 For this to work properly your event handler have to call `event.stopPropagation()`, for instance in `onPointerOver` or `onClick`, only one element can be selective for cycling to make sense.
@@ -874,10 +1117,14 @@ For this to work properly your event handler have to call `event.stopPropagation
 
 ![](https://img.shields.io/badge/-Dom only-red)
 
-This component allows you to select/unselect objects by clicking on them. It keeps track of the currently selected objects and can select multiple objects (with the shift key). Nested components can request the current selection (which is always an array) with the `useSelect` hook. With the `box` prop it will let you shift-box-select objects by holding and draging the cursor over multiple objects.
+<p>
+  <a href="https://codesandbox.io/s/ny3p4"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/ny3p4/screenshot.png" alt="Demo"/></a>
+</p>
+
+This component allows you to select/unselect objects by clicking on them. It keeps track of the currently selected objects and can select multiple objects (with the shift key). Nested components can request the current selection (which is always an array) with the `useSelect` hook. With the `box` prop it will let you shift-box-select objects by holding and draging the cursor over multiple objects. Optionally you can filter the selected items as well as define in which shape they are stored by defining the `filter` prop.
 
 ```jsx
-<Select box multiple onChange={console.log}>
+<Select box multiple onChange={console.log} filter={items => items}>
   <Foo />
   <Bar />
 </Select>
@@ -929,7 +1176,7 @@ return <SomethingThatNeedsADepthBuffer depthBuffer={depthBuffer} />
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-usefbo--use-fbo-st)
 
-Creates a `THREE.WebGLRenderTarget` or `THREE.WebGLMultisampleRenderTarget`.
+Creates a `THREE.WebGLRenderTarget`.
 
 ```jsx
 const target = useFBO({
@@ -944,6 +1191,10 @@ The rendertarget is automatically disposed when unmounted.
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-usecamera--use-camera-st)
 
+<p>
+  <a href="https://codesandbox.io/s/py4db"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/py4db/screenshot.png" alt="Demo"/></a>
+</p>
+
 A hook for the rare case when you are using non-default cameras for heads-up-displays or portals, and you need events/raytracing to function properly (raycasting uses the default camera otherwise).
 
 ```jsx
@@ -959,6 +1210,7 @@ A hook for a quick way to add helpers to existing nodes in the scene. It handles
 ```jsx
 const mesh = useRef()
 useHelper(mesh, BoxHelper, 'cyan')
+useHelper(condition && mesh, BoxHelper, 'red') // you can passe false instead of the object ref to hide the helper
 
 <mesh ref={mesh} ... />
 ```
@@ -1015,6 +1267,10 @@ return (
 
 #### useIntersect
 
+<p>
+  <a href="https://codesandbox.io/s/gsm1y"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/gsm1y/screenshot.png" alt="Demo"/></a>
+</p>
+
 A very cheap frustum check that gives you a reference you can observe in order to know if the object has entered the view or is outside of it. This relies on [THREE.Object3D.onBeforeRender](https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender) so it only works on objects that are effectively rendered, like meshes, lines, sprites. It won't work on groups, object3d's, bones, etc.
 
 ```jsx
@@ -1022,12 +1278,66 @@ const ref = useIntersect((visible) => console.log('object is visible', visible))
 return <mesh ref={ref} />
 ```
 
+#### useBoxProjectedEnv
+
+<p>
+  <a href="https://codesandbox.io/s/s006f"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/s006f/screenshot.png" alt="Demo"/></a>
+</p>
+
+The cheapest possible way of getting reflections in threejs. This will box-project the current environment map onto a plane. It returns an object that you need to spread over its material. The spread object contains a ref, onBeforeCompile and customProgramCacheKey. If you combine it with drei/CubeCamera you can "film" a single frame of the environment and feed it to the material, thereby getting realistic reflections at no cost. Align it with the position and scale properties.
+
+```jsx
+const projection = useBoxProjectedEnv(
+  [0, 0, 0], // Position
+  [1, 1, 1] // Scale
+)
+
+<CubeCamera frames={1}>
+  {(texture) => (
+    <mesh>
+      <planeGeometry />
+      <meshStandardMaterial envMap={texture} {...projection} />
+    </mesh>
+  )}
+</CubeCamera>
+```
+
+#### useTrail
+
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-trail--use-trail-st)
+
+A hook to obtain an array of points that make up a [Trail](#trail). You can use this array to drive your own `MeshLine` or make a trail out of anything you please.
+
+Note: The hook returns a ref (`MutableRefObject<Vector3[]>`) this means updates to it will not trigger a re-draw, thus keeping this cheap.
+
+```js
+const points = useTrail(
+  target, // Required target object. This object will produce the trail.
+  {
+    length, // Length of the line
+    decay, // How fast the line fades away
+    local, // Wether to use the target's world or local positions
+    stride, // Min distance between previous and current point
+    interval, // Number of frames to wait before next calculation
+  }
+)
+
+// To use...
+useFrame(() => {
+  meshLineRef.current.position.setPoints(points.current)
+})
+```
+
 # Loading
 
 #### Loader
 
 ![](https://img.shields.io/badge/-Dom only-red)
 
+<p>
+  <a href="https://codesandbox.io/s/0buje"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/0buje/screenshot.png" alt="Demo"/></a>
+</p>
+
 A quick and easy loading overlay component that you can drop on top of your canvas. It's intended to "hide" the whole app, so if you have multiple suspense wrappers in your application, you should use multiple loaders. It will show an animated loadingbar and a percentage.
 
 ```jsx
@@ -1156,6 +1466,11 @@ const envMap = useCubeTexture(['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png',
 
 #### Instances
 
+<p>
+  <a href="https://codesandbox.io/s/h8o2d"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/h8o2d/screenshot.png" alt="Demo"/></a>
+  <a href="https://codesandbox.io/s/i6t0j"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/i6t0j/screenshot.png" alt="Demo"/></a>
+</p>
+
 A wrapper around [THREE.InstancedMesh](https://threejs.org/docs/#api/en/objects/InstancedMesh). This allows you to define hundreds of thousands of objects in a single draw call, but declaratively!
 
 ```jsx
@@ -1197,8 +1512,14 @@ You can define events on them!
 <Instance onClick={...} onPointerOver={...} />
 ```
 
+👉 Note: While creating instances declaratively keeps all the power of components with reduced draw calls, it comes at the cost of CPU overhead. For cases like foliage where you want no CPU overhead with thousands of intances you should use THREE.InstancedMesh such as in this [example](https://codesandbox.io/s/grass-shader-5xho4?file=/src/Grass.js).
+
 #### Merged
 
+<p>
+  <a href="https://codesandbox.io/s/l900i"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/l900i/screenshot.png" alt="Demo"/></a>
+</p>
+
 This creates instances for existing meshes and allows you to use them cheaply in the same scene graph. Each type will cost you exactly one draw call, no matter how many you use. `meshes` has to be a collection of pre-existing THREE.Mesh objects.
 
 ```jsx
@@ -1242,27 +1563,12 @@ A wrapper around [THREE.Points](https://threejs.org/docs/#api/en/objects/Points)
   limit={1000} // Optional: max amount of items (for calculating buffer size)
   range={1000} // Optional: draw-range
 >
-  <pointsMaterial />
+  <pointsMaterial vertexColors />
   <Point position={[1, 2, 3]} color="red" onClick={onClick} onPointerOver={onPointerOver} ... />
   // As many as you want, make them conditional, mount/unmount them, lazy load them, etc ...
 </Points>
 ```
 
-If you have a material that supports vertex colors (like drei/PointMaterial) you can have individual colors!
-
-```jsx
-<Points>
-  <PointMaterial />
-  <Point color="hotpink" />
-```
-
-Otherwise use any material you like:
-
-```jsx
-<Points>
-  <pointsMaterial vertexColors size={10} />
-```
-
 If you just want to use buffers for position, color and size, you can use the alternative API:
 
 ```jsx
@@ -1310,6 +1616,10 @@ useFrame(() => {
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-detailed--detailed-st)
 
+<p>
+  <a href="https://codesandbox.io/s/12nmp"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/12nmp/screenshot.png" alt="Demo"/></a>
+</p>
+
 A wrapper around [THREE.LOD](https://threejs.org/docs/#api/en/objects/LOD) (Level of detail).
 
 ```jsx
@@ -1356,7 +1666,7 @@ A very fast, but often good-enough bounds-only raycast for meshes. You can use t
 
 #### AdaptiveDpr
 
-Drop this component into your scene and it will cut the pixel-ratio on [regress](#) according to the canvases perrformance min/max settings. This allows you to temporarily reduce visuals for more performance, for instance when the camera moves (look into drei's controls `regress` flag). Optionally you can set the canvas to a pixelated filter, which would be even faster.
+Drop this component into your scene and it will cut the pixel-ratio on regress according to the canvas's performance min/max settings. This allows you to temporarily reduce visual quality in exchange for more performance, for instance when the camera moves (look into drei's controls regress flag). Optionally, you can set the canvas to a pixelated filter, which would be even faster.
 
 ```jsx
 <AdaptiveDpr pixelated />
@@ -1387,9 +1697,9 @@ useBVH(mesh)
 
 #### Center
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-center--default-story)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-center--default-story)
 
-Calculates a boundary box and centers its children accordingly. `alignTop` makes adjusts it so that it's sits flush on y=0.
+Calculates a boundary box and centers its children accordingly. `alignTop` adjusts it so that it sits flush on y=0.
 
 ```jsx
 <Center alignTop>
@@ -1399,10 +1709,14 @@ Calculates a boundary box and centers its children accordingly. `alignTop` makes
 
 #### Bounds
 
+<p>
+  <a href="https://codesandbox.io/s/rz2g0"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/rz2g0/screenshot.png" alt="Demo"/></a>
+</p>
+
 Calculates a boundary box and centers the camera accordingly. If you are using controls, make sure to pass them the `makeDefault` prop. `fit` fits the current view on first render. `clip` sets the cameras near/far planes.
 
 ```jsx
-<Bounds fit clip damping={6} margin={1.2}>
+<Bounds fit clip observe damping={6} margin={1.2}>
   <mesh />
 </Bounds>
 ```
@@ -1425,7 +1739,12 @@ function Foo() {
 
 #### CameraShake
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/camera-camerashake--camera-shake-st)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-camerashake--camera-shake-story)
+
+<p>
+  <a href="https://codesandbox.io/s/t4l0f"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/t4l0f/screenshot.png" alt="Demo"/></a>
+  <a href="https://codesandbox.io/s/0ycwe"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/0ycwe/screenshot.png" alt="Demo"/></a>
+</p>
 
 A component for applying a configurable camera shake effect. Currently only supports rotational camera shake. Pass a ref to recieve the `ShakeController` API.
 
@@ -1457,6 +1776,10 @@ interface ShakeController {
 
 #### Float
 
+<p>
+  <a href="https://codesandbox.io/s/2ij9u"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/2ij9u/screenshot.png" alt="Demo"/></a>
+</p>
+
 This component makes its contents float or hover.
 
 ```js
@@ -1471,7 +1794,7 @@ This component makes its contents float or hover.
 
 #### Stage
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/prototyping-stage--stage-st)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-stage--stage-st)
 
 Creates a "stage" with proper studio lighting, content centered and planar, shadows and ground-contact shadows.
 
@@ -1485,6 +1808,10 @@ Make sure to set the `makeDefault` prop on your controls, in that case you do no
 
 #### Backdrop
 
+<p>
+  <a href="https://codesandbox.io/s/8yfnd"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/8yfnd/screenshot.png" alt="Demo"/></a>
+</p>
+
 A curved plane, like a studio backdrop. This is for presentational purposes, to break up light and shadows more interestingly.
 
 ```jsx
@@ -1513,12 +1840,16 @@ A cheap canvas-texture-based circular gradient.
 
 #### ContactShadows
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/shaders-contactshadows--contact-shadow-st)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-contactshadows--contact-shadow-st)
+
+<p>
+  <a href="https://codesandbox.io/s/qxjoj"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/qxjoj/screenshot.png" alt="Demo"/></a>
+</p>
 
 A [contact shadow](https://threejs.org/examples/#webgl_shadow_contact) implementation, facing upwards (positive Y) by default. `scale` can be a positive number or a 2D array `[x: number, y: number]`.
 
 ```jsx
-<ContactShadows opacity={1} scale={10} blur={1} far={10} resolution={256} />
+<ContactShadows opacity={1} scale={10} blur={1} far={10} resolution={256} color="#000000" />
 ```
 
 Since this is a rather expensive effect you can limit the amount of frames it renders when your objects are static. For instance making it render only once:
@@ -1529,6 +1860,11 @@ Since this is a rather expensive effect you can limit the amount of frames it re
 
 #### SpotLight
 
+<p>
+  <a href="https://codesandbox.io/s/tx1pq"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/tx1pq/screenshot.png" alt="Demo"/></a>
+  <a href="https://codesandbox.io/s/wdzv4"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/wdzv4/screenshot.png" alt="Demo"/></a>
+</p>
+
 A Volumetric spotlight.
 
 ```jsx
@@ -1550,17 +1886,26 @@ function Foo() {
 
 #### Environment
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/abstractions-environment--environment-st)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-environment--environment-story)
+
+<p>
+  <a href="https://codesandbox.io/s/t4l0f"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/t4l0f/screenshot.png" alt="Demo"/></a>
+  <a href="https://codesandbox.io/s/mih0lx"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/mih0lx/screenshot.png" alt="Demo"/></a>
+  <a href="https://codesandbox.io/s/e662p3"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/e662p3/screenshot.png" alt="Demo"/></a>
+  <a href="https://codesandbox.io/s/lwo219"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/lwo219/screenshot.png" alt="Demo"/></a>
+</p>
 
 Sets up a global cubemap, which affects the default `scene.environment`, and optionally `scene.background`, unless a custom scene has been passed. A selection of [presets](src/helpers/environment-assets.ts) from [HDRI Haven](https://hdrihaven.com/) are available for convenience. If you pass an array of files it will use THREE.CubeTextureLoader.
 
+👉 Note: `preset` property is not meant to be used in production environments. Consider using `files` property together with local files or a CDN of your choice instead.
+
 ```jsx
 <Environment
-  background={false}
+  background={false} // can be true, false or "only" (which only sets the background) (default: false)
   files={['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png']}
   path="/"
   preset={null}
-  scene={undefined} // adds the ability to pass a custom THREE.Scene
+  scene={undefined} // adds the ability to pass a custom THREE.Scene, can also be a ref
 />
 ```
 
@@ -1570,9 +1915,67 @@ If you provide a single string it will use THREE.RGBELoader.
 <Environment files="file.hdr" />
 ```
 
+If you already have a cube texture you can pass it directly:
+
+```jsx
+<CubeCamera>{(texture) => <Environment map={texture} />}</CubeCamera>
+```
+
+If you provide children you can even render a custom environment. It will render the contents into an off-buffer and film a single frame with a cube camera (whose props you can configure: near=1, far=1000, resolution=256).
+
+```jsx
+<Environment background near={1} far={1000} resolution={256}>
+  <mesh scale={100}>
+    <sphereGeometry args={[1, 64, 64]} />
+    <meshBasicMaterial map={texture} side={THREE.BackSide} />
+  </mesh>
+</Environment>
+```
+
+You can even mix a generic HDRI environment into a custom one with either the `preset` or the `files` prop.
+
+```jsx
+return (
+  <Environment background near={1} far={1000} resolution={256} preset="warehouse">
+    <mesh />
+```
+
+Declarative environment content can also animate with the `frames` prop, the envmap can be live. Give it a low resolution and this will happen at very little cost
+
+```jsx
+return (
+  <Environment frames={Infinity} resolution={256}>
+    <Float>
+      <mesh />
+    </Float>
+```
+
+#### Lightformer
+
+<p>
+  <a href="https://codesandbox.io/s/lwo219"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/lwo219/screenshot.png" alt="Demo"/></a>
+</p>
+
+This component draws flat rectangles, circles or rings, mimicking the look of a light-former. You can set the output `intensity`, which will effect emissiveness once you put it into an HDRI `<Environment>`, where it mostly belong. It will act like a real light without the expense, you can have as many as you want.
+
+```jsx
+<Environment>
+  <Lightformer
+    form="rect" // circle | ring | rect (optional, default = rect)
+    intensity={1} // power level (optional = 1)
+    color="white" // (optional = white)
+    scale={[10, 5]} // Scale it any way you prefer (optional = [1, 1])
+    target={[0, 0, 0]} // Target position (optional = undefined)
+  />
+```
+
 #### Sky
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/shaders-sky--sky-st)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-sky--sky-st)
+
+<p>
+  <a href="https://codesandbox.io/s/vkgi6"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/vkgi6/screenshot.png" alt="Demo"/></a>
+</p>
 
 Adds a [sky](https://threejs.org/examples/#webgl_shaders_sky) to your scene.
 
@@ -1582,7 +1985,7 @@ Adds a [sky](https://threejs.org/examples/#webgl_shaders_sky) to your scene.
 
 #### Stars
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/shaders-stars--stars-st)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-stars--stars-st)
 
 Adds a blinking shader-based starfield to your scene.
 
@@ -1594,8 +1997,14 @@ Adds a blinking shader-based starfield to your scene.
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-cloud--cloud-st) ![](https://img.shields.io/badge/-suspense-brightgreen)
 
+<p>
+  <a href="https://codesandbox.io/s/mbfzf"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/mbfzf/screenshot.png" alt="Demo"/></a>
+</p>
+
 Particle based cloud.
 
+👉 Note: `<Cloud />` component is not meant to be used in production environments as it relies on third-party CDN.
+
 ```jsx
 <Cloud
   opacity={0.5}
@@ -1608,12 +2017,14 @@ Particle based cloud.
 
 #### useMatcapTexture
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/prototyping-usematcaptexture) ![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-usematcaptexture--use-matcap-texture-st) ![](https://img.shields.io/badge/-suspense-brightgreen)
 
 Loads matcap textures from this repository: https://github.com/emmelleppi/matcaps
 
 (It is a fork of this repository: https://github.com/nidorx/matcaps)
 
+👉 Note: `useMatcapTexture` hook is not meant to be used in production environments as it relies on third-party CDN.
+
 ```jsx
 const [matcap, url] = useMatcapTexture(
  0, // index of the matcap texture https://github.com/emmelleppi/matcaps/blob/master/matcap-list.json
@@ -1637,10 +2048,12 @@ const [matcap] = useMatcapTexture('3E2335_D36A1B_8E4A2E_2842A5')
 
 #### useNormalTexture
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/prototyping-usenormaltexture) ![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-usenormaltexture--use-normal-texture-st) ![](https://img.shields.io/badge/-suspense-brightgreen)
 
 Loads normal textures from this repository: https://github.com/emmelleppi/normal-maps
 
+👉 Note: `useNormalTexture` hook is not meant to be used in production environments as it relies on third-party CDN.
+
 ```jsx
 const [normalMap, url] = useNormalTexture(
   1, // index of the normal texture - https://github.com/emmelleppi/normal-maps/blob/master/normals.json