diff --git a/docs/API/additional-exports.mdx b/docs/API/additional-exports.mdx index d8f11d29a9..075def88bb 100644 --- a/docs/API/additional-exports.mdx +++ b/docs/API/additional-exports.mdx @@ -3,21 +3,21 @@ title: Additional Exports nav: 9 --- -| export | usage | -| ------------------ | -------------------------------------------------------------- | -| addEffect | Adds a global render callback which is called each frame | -| addAfterEffect | Adds a global after-render callback which is called each frame | -| addTail | Adds a global callback which is called when rendering stops | -| buildGraph | Collects nodes and materials from a THREE.Object3D | -| flushGlobalEffects | Flushes global render-effects for when manually driving a loop | -| flushSync | Force React to flush any updates synchronously and immediately | -| invalidate | Forces view global invalidation | -| advance | Advances the frameloop (given that it's set to 'never') | -| extend | Extends the native-object catalogue | -| createPortal | Creates a portal (it's a React feature for re-parenting) | -| createRoot | Creates a root that can render three JSX into a canvas | -| events | Dom pointer-event system | -| applyProps | `applyProps(element, props)` sets element properties, | -| act | usage with react-testing | -| useInstanceHandle | Exposes react-internal local state from `instance.__r3f` | -| | | +| export | usage | +| -------------------- | -------------------------------------------------------------- | +| `addEffect` | Adds a global render callback which is called each frame | +| `addAfterEffect` | Adds a global after-render callback which is called each frame | +| `addTail` | Adds a global callback which is called when rendering stops | +| `buildGraph` | Collects nodes and materials from a THREE.Object3D | +| `flushGlobalEffects` | Flushes global render-effects for when manually driving a loop | +| `flushSync` | Force React to flush any updates synchronously and immediately | +| `invalidate` | Forces view global invalidation | +| `advance` | Advances the frameloop (given that it's set to 'never') | +| `extend` | Extends the native-object catalogue | +| `createPortal` | Creates a portal (it's a React feature for re-parenting) | +| `createRoot` | Creates a root that can render three JSX into a canvas | +| `events` | Dom pointer-event system | +| `applyProps` | `applyProps(element, props)` sets element properties, | +| `act` | usage with react-testing | +| `useInstanceHandle` | Exposes react-internal local state from `instance.__r3f` | +| | | diff --git a/docs/API/hooks.mdx b/docs/API/hooks.mdx index 281e0727da..bb76ec4a69 100644 --- a/docs/API/hooks.mdx +++ b/docs/API/hooks.mdx @@ -35,7 +35,7 @@ function App() { ``` -## useThree +## `useThree` This hook gives you access to the state model which contains the default renderer, the scene, your camera, and so on. It also gives you the current size of the canvas in screen and viewport coordinates. @@ -48,35 +48,35 @@ function Foo() { The hook is reactive, if you resize the browser for instance, you get fresh measurements, same applies to any of the state objects that may change. -### State properties - -| Prop | Description | Type | -| --------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| gl | Renderer | `THREE.WebGLRenderer` | -| scene | Scene | `THREE.Scene` | -| camera | Camera | `THREE.PerspectiveCamera` | -| raycaster | Default raycaster | `THREE.Raycaster` | -| pointer | Contains updated, normalized, centric pointer coordinates | `THREE.Vector2` | -| mouse | Note: this is deprecated, use `pointer` instead! Normalized event coordinates | `THREE.Vector2` | -| clock | Running system clock | `THREE.Clock` | -| linear | True when the colorspace is linear | `boolean` | -| flat | True when no tonemapping is used | `boolean` | -| legacy | Disables global color management via `THREE.ColorManagement` | `boolean` | -| frameloop | Render mode: always, demand, never | `always`, `demand`, `never` | -| performance | System regression | `{ current: number, min: number, max: number, debounce: number, regress: () => void }` | -| size | Canvas size in pixels | `{ width: number, height: number, top: number, left: number, updateStyle?: boolean }` | -| viewport | Viewport size in three.js units | `{ width: number, height: number, initialDpr: number, dpr: number, factor: number, distance: number, aspect: number, getCurrentViewport: (camera?: Camera, target?: THREE.Vector3, size?: Size) => Viewport }` | -| xr | XR interface, manages WebXR rendering | `{ connect: () => void, disconnect: () => void }` | -| set | Allows you to set any state property | `(state: SetState) => void` | -| get | Allows you to retrieve any state property non-reactively | `() => GetState` | -| invalidate | Request a new render, given that `frameloop === 'demand'` | `() => void` | -| advance | Advance one tick, given that `frameloop === 'never'` | `(timestamp: number, runGlobalEffects?: boolean) => void` | -| setSize | Resize the canvas | `(width: number, height: number, updateStyle?: boolean, top?: number, left?: number) => void` | -| setDpr | Set the pixel-ratio | `(dpr: number) => void` | -| setFrameloop | Shortcut to set the current render mode | `(frameloop?: 'always', 'demand', 'never') => void` | -| setEvents | Shortcut to setting the event layer | `(events: Partial>) => void` | -| onPointerMissed | Response for pointer clicks that have missed a target | `() => void` | -| events | Pointer-event handling | `{ connected: TargetNode, handlers: Events, connect: (target: TargetNode) => void, disconnect: () => void }` | +### `state` properties + +| Prop | Description | Type | +| ----------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `gl` | Renderer | `THREE.WebGLRenderer` | +| `scene` | Scene | `THREE.Scene` | +| `camera` | Camera | `THREE.PerspectiveCamera` | +| `raycaster` | Default raycaster | `THREE.Raycaster` | +| `pointer` | Contains updated, normalized, centric pointer coordinates | `THREE.Vector2` | +| `mouse` | Note: this is deprecated, use `pointer` instead! Normalized event coordinates | `THREE.Vector2` | +| `clock` | Running system clock | `THREE.Clock` | +| `linear` | True when the colorspace is linear | `boolean` | +| `flat` | True when no tonemapping is used | `boolean` | +| `legacy` | Disables global color management via `THREE.ColorManagement` | `boolean` | +| `frameloop` | Render mode: always, demand, never | `always`, `demand`, `never` | +| `performance` | System regression | `{ current: number, min: number, max: number, debounce: number, regress: () => void }` | +| `size` | Canvas size in pixels | `{ width: number, height: number, top: number, left: number, updateStyle?: boolean }` | +| `viewport` | Viewport size in three.js units | `{ width: number, height: number, initialDpr: number, dpr: number, factor: number, distance: number, aspect: number, getCurrentViewport: (camera?: Camera, target?: THREE.Vector3, size?: Size) => Viewport }` | +| `xr` | XR interface, manages WebXR rendering | `{ connect: () => void, disconnect: () => void }` | +| `set` | Allows you to set any state property | `(state: SetState) => void` | +| `get` | Allows you to retrieve any state property non-reactively | `() => GetState` | +| `invalidate` | Request a new render, given that `frameloop === 'demand'` | `() => void` | +| `advance` | Advance one tick, given that `frameloop === 'never'` | `(timestamp: number, runGlobalEffects?: boolean) => void` | +| `setSize` | Resize the canvas | `(width: number, height: number, updateStyle?: boolean, top?: number, left?: number) => void` | +| `setDpr` | Set the pixel-ratio | `(dpr: number) => void` | +| `setFrameloop` | Shortcut to set the current render mode | `(frameloop?: 'always', 'demand', 'never') => void` | +| `setEvents` | Shortcut to setting the event layer | `(events: Partial>) => void` | +| `onPointerMissed` | Response for pointer clicks that have missed a target | `() => void` | +| `events` | Pointer-event handling | `{ connected: TargetNode, handlers: Events, connect: (target: TargetNode) => void, disconnect: () => void }` | ### Selector @@ -111,7 +111,7 @@ function Foo() { }, []) ``` -## useFrame +## `useFrame` This hook allows you to execute code on every rendered frame, like running effects, updating controls, and so on. You receive the state (same as `useThree`) and a clock delta. Your callback function will be invoked just before a frame is rendered. When the component unmounts it is unsubscribed automatically from the render-loop. @@ -163,7 +163,7 @@ function B() { useFrame(() => ..., -1) ``` -## useLoader +## `useLoader` This hook loads assets and suspends for easier fallback- and error-handling. It can take any three.js loader as its first argument: GLTFLoader, OBJLoader, TextureLoader, FontLoader, etc. It is based on [React.Suspense](https://react.dev/reference/react/Suspense), so fallback-handling and [error-handling](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) happen at the parental level. @@ -242,7 +242,7 @@ You can pre-load assets in global space so that models can be loaded in anticipa useLoader.preload(GLTFLoader, '/model.glb' /* extensions */) ``` -## useGraph +## `useGraph` Convenience hook which creates a memoized, named object/material collection from any [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D). diff --git a/docs/advanced/pitfalls.mdx b/docs/advanced/pitfalls.mdx index afb6882f35..3b974aaa00 100644 --- a/docs/advanced/pitfalls.mdx +++ b/docs/advanced/pitfalls.mdx @@ -28,7 +28,7 @@ TLDR, don't, mutate inside `useFrame`! - You might be tempted to setState inside `useFrame` but there is no reason to. You would only complicate something as simple as an update by routing it through React's scheduler, triggering component render etc. -### ❌ setState in loops is bad +### ❌ `setState` in loops is bad ```jsx useEffect(() => { @@ -37,7 +37,7 @@ useEffect(() => { }, []) ``` -### ❌ setState in useFrame is bad +### ❌ `setState` in useFrame is bad ```jsx const [x, setX] = useState(0) @@ -45,7 +45,7 @@ useFrame(() => setX((x) => x + 0.1)) return ``` -### ❌ setState in fast events is bad +### ❌ `setState` in fast events is bad ```jsx setX((x) => e.point.x)} /> @@ -80,7 +80,7 @@ useEffect(() => { The frame loop is where you should place your animations. For instance using lerp, or damp. -### ✅ Use lerp + useFrame +### ✅ Use `lerp` + `useFrame` ```jsx function Signal({ active }) { @@ -157,7 +157,7 @@ function Stage1(props) { ... ``` -### ✅ Use startTransition for expensive ops +### ✅ Use `startTransition` for expensive ops React 18 introduces the `startTransition` and `useTransition` APIs to defer and schedule work and state updates. Use these to de-prioritize expensive operations. @@ -213,7 +213,7 @@ function Foo(props) }) ``` -## useLoader instead of plain loaders +## `useLoader` instead of plain loaders Threejs loaders give you the ability to load async assets (models, textures, etc), but if you do not re-use assets it can quickly become problematic. diff --git a/docs/advanced/scaling-performance.mdx b/docs/advanced/scaling-performance.mdx index 45b686a4cb..9ffda44498 100644 --- a/docs/advanced/scaling-performance.mdx +++ b/docs/advanced/scaling-performance.mdx @@ -94,7 +94,7 @@ THREE.ColorManagement.enabled = true THREE.ColorManagement.legacyMode = false ``` -### Caching with useLoader +### Caching with `useLoader` > [!NOTE] > Every resource that is loaded with useLoader is cached automatically! @@ -271,11 +271,11 @@ performance: { }, ``` -- current: Performance factor alternates between min and max -- min: Performance lower bound (should be less than 1) -- max: Performance upper bound (no higher than 1) -- debounce: Debounce timeout until it goes to upper bound (1) again -- regress(): Function that temporarily regresses performance +- `current`: Performance factor alternates between min and max +- `min`: Performance lower bound (should be less than 1) +- `max`: Performance upper bound (no higher than 1) +- `debounce`: Debounce timeout until it goes to upper bound (1) again +- `regress()`: Function that temporarily regresses performance You can define defaults like so: diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx index a137ed65df..26bc689ada 100644 --- a/docs/getting-started/installation.mdx +++ b/docs/getting-started/installation.mdx @@ -182,7 +182,7 @@ module.exports = { } ``` -R3F's API is completely x-platform, so you can use [events](https://docs.pmnd.rs/react-three-fiber/api/events) and [hooks](https://docs.pmnd.rs/react-three-fiber/api/hooks) just as you would on the web. +R3F's API is completely x-platform, so you can use [events](/api/events) and [hooks](/api/hooks) just as you would on the web. > [!NOTE] > Make sure to import from `@react-three/fiber/native` or `@react-three/drei/native` for correct IntelliSense and platform-specific abstractions. diff --git a/docs/getting-started/introduction.mdx b/docs/getting-started/introduction.mdx index 316787c781..1bec37f287 100644 --- a/docs/getting-started/introduction.mdx +++ b/docs/getting-started/introduction.mdx @@ -4,10 +4,9 @@ description: React-three-fiber is a React renderer for three.js. nav: 0 --- - + -
Build your scene declaratively with re-usable, self-contained components that react to state, are readily interactive and can participate in React's ecosystem. @@ -15,15 +14,15 @@ Build your scene declaratively with re-usable, self-contained components that re npm install three @types/three @react-three/fiber ``` -#### Does it have limitations? +## Does it have limitations? None. Everything that works in Threejs will work here without exception. -#### Is it slower than plain Threejs? +## Is it slower than plain Threejs? No. There is no overhead. Components render outside of React. It outperforms Threejs in scale due to React's scheduling abilities. -#### Can it keep up with frequent feature updates to Threejs? +## Can it keep up with frequent feature updates to Threejs? Yes. It merely expresses Threejs in JSX, `` dynamically turns into `new THREE.Mesh()`. If a new Threejs version adds, removes or changes features, it will be available to you instantly without depending on updates to this library. @@ -147,7 +146,7 @@ createRoot(document.getElementById('root')).render(
Show React Native example -For installation instructions see [react native installation instructions](https://docs.pmnd.rs/react-three-fiber/getting-started/installation#react-native). +For installation instructions see [react native installation instructions](/getting-started/installation#react-native). ```jsx import React, { useRef, useState } from 'react' @@ -194,7 +193,7 @@ You need to be versed in both React and Threejs before rushing into this. If you 1. Make sure you have a [basic grasp of Threejs](https://threejs.org/docs/index.html#manual/en/introduction/Creating-a-scene). Keep that site open. 2. When you know what a scene is, a camera, mesh, geometry, material, fork the [demo above](https://github.com/pmndrs/react-three-fiber#what-does-it-look-like). 3. [Look up](https://threejs.org/docs/index.html#api/en/objects/Mesh) the JSX elements that you see (mesh, ambientLight, etc), _all_ threejs exports are native to three-fiber. -4. Try changing some values, scroll through our [API](https://docs.pmnd.rs/react-three-fiber) to see what the various settings and hooks do. +4. Try changing some values, scroll through our [API](/api/canvas) to see what the various settings and hooks do. Some helpful material: diff --git a/docs/getting-started/your-first-scene.mdx b/docs/getting-started/your-first-scene.mdx index 6ea70af276..c574b20d46 100644 --- a/docs/getting-started/your-first-scene.mdx +++ b/docs/getting-started/your-first-scene.mdx @@ -46,7 +46,7 @@ To actually see something in our scene, we'll add a lowercase `` native > Note that we don't need to import anything, All three.js objects will be treated as native JSX elements, just like you can just write <div /> or <span /> in regular ReactDOM. The general rule is that Fiber components are available under the camel-case version of their name in three.js. A [`Mesh`](https://threejs.org/docs/#api/en/objects/Mesh) is a basic scene object in three.js, and it's used to hold the geometry and the material needed to represent a shape in 3D space. -We'll create a new mesh using a **BoxGeometry** and a **MeshStandardMaterial** which [automatically attach](https://docs.pmnd.rs/react-three-fiber/api/objects#attach) to their parent. +We'll create a new mesh using a **BoxGeometry** and a **MeshStandardMaterial** which [automatically attach](/api/objects#attach) to their parent. ```jsx diff --git a/docs/tutorials/basic-animations.mdx b/docs/tutorials/basic-animations.mdx index 350b80868f..eb237a314e 100644 --- a/docs/tutorials/basic-animations.mdx +++ b/docs/tutorials/basic-animations.mdx @@ -8,7 +8,7 @@ This tutorial will assume some React knowledge, and will be based on [this start We will build a really small, continuous animation loop, that will be the basic building block of more advanced animations later on. -## useFrame +## `useFrame` `useFrame` is a Fiber hook that lets you execute code on every frame of Fiber's render loop. This can have a lot of uses, but we will focus on building an animation with it. diff --git a/docs/tutorials/loading-models.mdx b/docs/tutorials/loading-models.mdx index 537530aea8..d53052476c 100644 --- a/docs/tutorials/loading-models.mdx +++ b/docs/tutorials/loading-models.mdx @@ -139,7 +139,7 @@ You can play with the sandbox here: -### Loading FBX models using useFBX +### Loading FBX models using `useFBX` [@react-three/drei](https://github.com/pmndrs/drei) exports a very useful helper when it comes to loading FBX models and it's called `useFBX`, in this case there is no need to import anything from `three.js` as it is all done behind the scenes and we can just pass the location of the file to `useFBX` like so: diff --git a/docs/tutorials/loading-textures.mdx b/docs/tutorials/loading-textures.mdx index 0d9e008db9..adebac331d 100644 --- a/docs/tutorials/loading-textures.mdx +++ b/docs/tutorials/loading-textures.mdx @@ -6,7 +6,7 @@ nav: 15 > All textures used in this chapter were downloaded from [cc0textures](https://cc0textures.com/). -## Using TextureLoader & useLoader +## Using `TextureLoader` and `useLoader` To load the textures we will use the `TextureLoader` from three.js in combination with `useLoader` that will allow us to pass the location of the texture and get the map back. @@ -108,7 +108,7 @@ function Scene() { } ``` -## Using useTexture +## Using `useTexture` Another way to import these is using `useTexture` from [`@react-three/drei`](https://github.com/pmndrs/drei), that will make it slightly easier and there is no need to import the `TextureLoader`, our code would look like: diff --git a/docs/tutorials/typescript.mdx b/docs/tutorials/typescript.mdx index 55cc4cdbac..64d6312bdc 100644 --- a/docs/tutorials/typescript.mdx +++ b/docs/tutorials/typescript.mdx @@ -6,7 +6,7 @@ nav: 18 This tutorial will assume some React and TypeScript knowledge. You can fork and follow along from [this starter codesandbox](https://codesandbox.io/s/brnsm). -## Typing with useRef +## Typing with `useRef` React's `useRef` won't automatically infer types despite pointing it to a typed ref. @@ -63,7 +63,7 @@ color: Color This is particularly useful if you are typing properties outside of components, such as a store or a hook. -## Extend usage +## `extend` usage react-three-fiber can also accept third-party elements and extend them into its internal catalogue. @@ -101,7 +101,7 @@ MaterialNode LightNode ``` -### Extending ThreeElements +### Extending `ThreeElements` Since our custom element is an object, we'll use `Object3DNode` to define it. diff --git a/docs/tutorials/v8-migration-guide.mdx b/docs/tutorials/v8-migration-guide.mdx index b262bf5c67..d79c9885aa 100644 --- a/docs/tutorials/v8-migration-guide.mdx +++ b/docs/tutorials/v8-migration-guide.mdx @@ -135,7 +135,7 @@ Please be careful, this is an extreme stress test. It creates so much load that

-## Conditional rendering with frameloop +## Conditional rendering with `frameloop` `frameloop` can now be toggled to render conditionally. This is useful to toggle on user interaction or while in frame. @@ -166,7 +166,7 @@ useEffect(() => { ``` -## Expanded gl prop +## Expanded `gl` prop The `gl` prop can now accept both constructor args and renderer properties like the `camera` prop. @@ -193,7 +193,7 @@ The `vr` prop was removed in favor of automatic WebXR switching. Whenever a sess + ``` -### Extended useFrame +### Extended `useFrame` In addition to the automatic rendering, useFrame will expose the current [`XRFrame`](https://developer.mozilla.org/en-US/docs/Web/API/XRFrame) obtained via [XRSession#requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/XRSession/requestAnimationFrame). @@ -203,7 +203,7 @@ useFrame((state: RootState, delta: number, frame?: THREE.XRFrame) => { ... }) This removes the need for custom rendering loops when using WebXR pose data and abstractions like `useXRFrame` of [@react-three/xr](https://github.com/pmndrs/react-xr). -## Manual camera manipulation +## Manual `camera` manipulation By default Fiber is responsive and will set up cameras properly on resize (aspect ratio etc). @@ -222,7 +222,7 @@ import { PerspectiveCamera } from '@react-three/drei' ``` -## Unified attach API +## Unified `attach` API Previously, attach had multiple signatures: @@ -292,7 +292,7 @@ Arrays must be explcit now: ``` -## Spread Canvas props +## Spread `Canvas` props The `` can now accept non-render props to spread as native props: styles, classes, events, a11y, ... @@ -303,7 +303,7 @@ The `` can now accept non-render props to spread as native props: styl + ``` -## New createRoot API +## New `createRoot` API `render` is depreciated in v8 for the new `createRoot` signature. @@ -352,7 +352,7 @@ This is a custom-renderer example using the createRoot api:

-## Tree-shaking via extend +## Tree-shaking via `extend` The underlying reconciler no longer pulls in the THREE namespace automatically. @@ -407,7 +407,7 @@ createRoot(canvasNode).render( No changes are necessary for `@react-three/test-renderer` as THREE is extended automatically. -## createPortal creates a state enclave +## `createPortal` creates a state enclave `createPortal` allows you to write a declarative JSX scene into a pre-existing, foreign object. This has been very useful for portals, heads-up displays, view-cubes, view splitting, etc.