r3f-scroll-rig

When using <UseCanvas/>, be aware of two key behaviors:

1. HMR (Hot Module Replacement): HMR might not work for the children of <UseCanvas> unless you define those children outside the component.
2. Reactivity: The props passed to children of <UseCanvas> are not reactive by default because the component is tunneled to the global canvas. To handle updated props, you must use the tunneling pattern described in the API documentation.

The library uses a single shared <GlobalCanvas/> that persists across page loads to avoid the browser limits of multiple WebGL contexts.

To render WebGL content, React DOM components use the <UseCanvas/> tunnel component or the useCanvas() hook to send their children to this global canvas.

To synchronize WebGL objects with the DOM during scrolling, the library uses "proxy" elements in the normal page flow. Components like <ScrollScene/>, <ViewportScrollScene/>, or the useTracker() hook detect the initial location and dimensions of these proxy elements and update the WebGL scene positions in lockstep with the scrollbar position on the main thread.

To ensure 3D objects scale correctly across different screen sizes, always base your mesh sizes on the scale value provided by ScrollScene, ViewportScrollScene, or the useTracker hook. This scale matches the tracked DOM element and updates automatically with media queries.

The scale is a 3-dimensional vector from the vecn package, supporting swizzling (e.g., scale.xy) and object notation.

<ScrollScene track={el}>
  {({ scale }) => (
    <mesh scale={scale} />
  )}
</ScrollScene>

To ensure WebGL objects and DOM content match perfectly, you must add <GlobalCanvas/> and <SmoothScrollbar/> to your application layout.

Important: Keep <GlobalCanvas/> outside of your router so it does not unmount during navigation. <SmoothScrollbar/> is required to animate the browser scroll position on the main thread for synchronization.

// Next.js example (_app.jsx)
import { GlobalCanvas, SmoothScrollbar } from '@14islands/r3f-scroll-rig'

function App({ Component, pageProps }) {
  return (
    <>
      <GlobalCanvas />
      <SmoothScrollbar />
      <Component {...pageProps} />
    </>
  )
}

To avoid bundling react-three-fiber unnecessarily, import the scrollbar-specific components and hooks from the @14islands/r3f-scroll-rig/scrollbar subpath instead of the main entry point.

import { SmoothScrollbar, useScrollbar, useTracker } from '@14islands/r3f-scroll-rig/scrollbar'

Because post-processing runs in a separate pass, you must disable the default global render loop to avoid double renders when using effects.

<GlobalCanvas globalRender={false} scaleMultiplier={0.01}>
  <Effects />
</GlobalCanvas>

R3F uses ACES Filmic tone mapping by default. If you need to display editorial images or match specific hex colors exactly, disable tone mapping on the specific material.

<meshBasicMaterial toneMapping={false} />

To allow R3F events to work correctly on a scrolling page, re-attach the event system to a parent DOM element of the canvas. This allows events to be captured from the DOM and tunneled into the canvas.

const ref = useRef()
return (
  <div ref={ref}>
    <GlobalCanvas
      eventSource={ref} // rebind event source to a parent DOM element
      eventPrefix="client" // use clientX/Y for a scrolling page
      style={{
        pointerEvents: 'none', // delegate events to wrapper
      }}
    />
  </div>
)

Install the core package along with its peer dependencies @react-three/fiber and three using yarn:

yarn add @14islands/r3f-scroll-rig @react-three/fiber three

By default, the library calculates camera FoV so that 1 pixel = 1 viewport unit. On large screens, this results in very large scene units and high Z-axis distances, which can cause depth sorting glitches (Z-fighting).

A performant way to fix this is to set the scaleMultiplier prop on GlobalCanvas to a smaller value (e.g., 0.01). This scales down the internal camera and scaling logic (e.g., 1000px becomes 10 viewport units).

Note: If you change this setting, any hardcoded scales or positions in your scene will need to be updated.

<GlobalCanvas scaleMultiplier={0.01} />

You can render a Three.js object that follows a specific DOM element by using <UseCanvas/> and <ScrollScene/>. The <ScrollScene/> component takes a track prop (a React ref to a DOM element) and provides transformation props to its children to match the element's scale and position.

import { UseCanvas, ScrollScene } from '@14islands/r3f-scroll-rig'
import { useRef } from 'react'

export const HtmlComponent = () => {
  const el = useRef()
  return (
    <>
      <div ref={el}>Track me!</div>
      <UseCanvas>
        <ScrollScene track={el}>
          {(props) => (
            <mesh {...props}>
              <planeGeometry />
              <meshBasicMaterial color="turquoise" />
            </mesh>
          )}
        </ScrollScene>
      </UseCanvas>
    </>
  )
}