@threlte/core

useFrame

This hook allows you to execute code on every frame as part of the unified frameloop. You receive the state (the same as useThrelte) and a clock delta in seconds. Your callback function will be invoked just before a frame is rendered. When the component unmounts it is unsubscribed automatically from the frame loop.

You may pass additional options to this hook. The property order is useful if you need to order the sequence of useFrame callbacks across the component tree where callbacks are ordered from low to high. To debug your frameloop, provide a debugFrameloopMessage and add debugFrameloop to your <Canvas> component.

type ThrelteUseFrameOptions = {
  autostart?: boolean
  order?: number
  debugFrameloopMessage?: string
  invalidate?: boolean
}

useFrame returns an object containing functions start and stop to control the execution of the callback and a store started to subscribe to its state.

Example

Starting and stopping the execution of a frameloop handler:

const { start, stop, started } = useFrame(
  () => {
    console.log('rendering…')
  },
  {
    autostart: false
  }
)

const toggleUseFrame = () => {
  if ($started) {
    stop()
  } else {
    start()
  }
}

Accessing the context and the global clocks delta inside a frameloop handler:

useFrame(({ camera }, delta) => {
  const cameraPosition = camera.current.position
})

By default, useFrame will invalidate every frame and trigger a render after the callback is executed. You can disable this behavior by setting invalidate to false and using the function invalidate from the state to trigger a render manually.

useFrame(
  ({ invalidate }) => {
    // manually invalidate the frame
    invalidate()
  },
  {
    invalidate: false
  }
)