Interface ScrollRendererOptions

How the canvas is kept over the viewport.

• 'fixed' (default) — the canvas is position: fixed. Scene positions are read from the DOM every frame. Because native scrolling runs on the compositor thread, any scroll that lands between two animation frames moves the page without moving the canvas contents, which shows as scenes lagging behind their elements during momentum scrolling on touch devices.

• 'absolute' — the canvas is position: absolute at the top of the document and is translated back over the viewport every frame. Between frames the compositor scrolls the canvas with the page, so scenes stay attached to their elements. The one-frame lag instead shows at the canvas edge, which is hidden by rendering the canvas taller than the viewport (see ScrollRendererOptions.overscan). In this mode the renderer owns the canvas height and transform styles; you still position it (position: absolute; top: 0; left: 0; width: 100%; pointer-events: none) and should append it to document.body or another non-positioned ancestor so it is document-relative.

  Avoid this mode for scenes anchored to viewport-pinned elements (e.g. a position: fixed background) — those will exhibit the lag instead. To let scenes draw into the overscan band before they enter the viewport, set their margin to roughly ScrollRenderer.overscanPx.

Called once per frame after all scenes are rendered.

Called once per frame before any scenes are rendered.

Fraction of the viewport height added above and below the canvas when layout is 'absolute'. Larger values hide the leading edge during faster scrolls at the cost of more pixels rendered. Ignored in 'fixed' layout.

Props forwarded to the underlying Renderer. autoClear is always overridden to false.

Pass canvas here to use an existing <canvas> element instead of letting the renderer create one. This is particularly useful in React, where you can attach a ref to a <canvas> and pass the element in:

const canvasRef = useRef<HTMLCanvasElement>(null)
// inside useEffect:
new ScrollRenderer({ rendererProps: { canvas: canvasRef.current } })
Copy

When supplying your own canvas you are responsible for positioning it (see ScrollRendererOptions.layout for what that means in each mode) and for removing it from the DOM on teardown.