Motion GPU

API Reference

Hooks API

Reference for runtime hooks: useFrame, useMotionGPU, usePointer, useTexture, and user context APIs.

Reference for hook-based runtime control in the Svelte, React, and Vue adapters.

Entrypoints

Entrypoint Exports
@motion-core/motion-gpu/svelte useFrame, useMotionGPU, usePointer, useTexture
@motion-core/motion-gpu/svelte/advanced Everything above + useMotionGPUUserContext, setMotionGPUUserContext
@motion-core/motion-gpu/react useFrame, useMotionGPU, usePointer, useTexture
@motion-core/motion-gpu/react/advanced Everything above + useMotionGPUUserContext, useSetMotionGPUUserContext, setMotionGPUUserContext
@motion-core/motion-gpu/vue useFrame, useMotionGPU, usePointer, useTexture
@motion-core/motion-gpu/vue/advanced Everything above + useMotionGPUUserContext, setMotionGPUUserContext

Context rule

useFrame(), useMotionGPU(), usePointer(), and useMotionGPUUserContext() must run inside the <FragCanvas> subtree. In React, useSetMotionGPUUserContext() follows the same rule.

useFrame

useFrame(callback: (state: FrameState) => void, options?: UseFrameOptions)
useFrame(key: FrameKey, callback: (state: FrameState) => void, options?: UseFrameOptions)
useFrame(callback: (state: FrameState) => void, options?: UseFrameOptions)
useFrame(key: FrameKey, callback: (state: FrameState) => void, options?: UseFrameOptions)

UseFrameOptions

Field Type Default
autoStart boolean true
autoInvalidate boolean true
invalidation FrameTaskInvalidation Implicit
stage FrameKey FrameStage Main stage
before task ref or list undefined
after task ref or list undefined
running () => boolean undefined

Dependency validation is strict: cyclic graphs and missing before/after references throw.

FrameState

Field Type
time number
delta number
canvas HTMLCanvasElement
renderMode RenderMode
autoRender boolean
setUniform (name: string, value: UniformValue) => void
setTexture (name: string, value: TextureValue) => void
writeStorageBuffer (name: string, data: ArrayBufferView, options?: { offset?: number }) => void
readStorageBuffer (name: string) => Promise<ArrayBuffer>
invalidate (token?: FrameInvalidationToken) => void
advance () => void

useMotionGPU

Returns runtime context controls:

  • reactive size/dpr/mode stores
  • scheduler handle
  • invalidate() and advance()
  • access to shared user current-writable map

See: Hooks and Context.

usePointer(options?)

usePointer(options?: UsePointerOptions): UsePointerResult
usePointer(options?: UsePointerOptions): UsePointerResult

UsePointerOptions

Field Type Default
enabled boolean true
requestFrame 'auto' 'invalidate' 'advance' 'none' 'auto'
capturePointer boolean true
trackWhilePressedOutsideCanvas boolean true
clickEnabled boolean true
clickMaxDurationMs number 350
clickMaxMovePx number 8
clickButtons number[] [0]
onMove (state, event) => void undefined
onDown (state, event) => void undefined
onUp (state, event) => void undefined
onClick (click, state, event) => void undefined

Return: UsePointerResult

Field Type
state CurrentReadable<PointerState>
lastClick CurrentReadable<PointerClick null>
resetClick () => void

PointerState highlights

Field Type Notes
px [number, number] CSS pixels relative to canvas
uv [number, number] 0..1 with Y-up orientation
ndc [number, number] -1..1 with Y-up orientation
inside boolean Pointer currently inside canvas bounds
pressed boolean Active pointer is down
dragging boolean Active pointer moved while pressed
deltaPx / deltaUv tuple Per-event movement delta
velocityPx / velocityUv tuple Per-event velocity

useTexture(urlInput, options?)

URL input

Form Type
Static string[]
Dynamic () => string[]

TextureLoadOptions

Field Type Default
colorSpace 'srgb' 'linear' 'srgb'
requestInit RequestInit undefined
decode TextureDecodeOptions Auto
signal AbortSignal undefined
update TextureUpdateMode undefined
flipY boolean undefined
premultipliedAlpha boolean undefined
generateMipmaps boolean undefined

Return: UseTextureResult

Field Type
textures CurrentReadable<LoadedTexture[] null>
loading CurrentReadable<boolean>
error CurrentReadable<Error null>
errorReport CurrentReadable<MotionGPUErrorReport null>
reload () => Promise<void>

Advanced user context

useMotionGPUUserContext(): CurrentReadable<Record<MotionGPUUserNamespace, unknown>>
useMotionGPUUserContext<T>(namespace: MotionGPUUserNamespace): CurrentReadable<T | undefined>
useMotionGPUUserContext(): CurrentReadable<Record<MotionGPUUserNamespace, unknown>>
useMotionGPUUserContext<T>(namespace: MotionGPUUserNamespace): CurrentReadable<T | undefined>
setMotionGPUUserContext<T>(
  namespace: MotionGPUUserNamespace,
  value: T | (() => T),
  options?: SetMotionGPUUserContextOptions
): T | undefined
setMotionGPUUserContext<T>(
  namespace: MotionGPUUserNamespace,
  value: T | (() => T),
  options?: SetMotionGPUUserContextOptions
): T | undefined
useSetMotionGPUUserContext(): <T>(
  namespace: MotionGPUUserNamespace,
  value: T | (() => T),
  options?: SetMotionGPUUserContextOptions
) => T | undefined
useSetMotionGPUUserContext(): <T>(
  namespace: MotionGPUUserNamespace,
  value: T | (() => T),
  options?: SetMotionGPUUserContextOptions
) => T | undefined

In React, prefer useSetMotionGPUUserContext() for effect and event-handler writes.

SetMotionGPUUserContextOptions:

Field Values Default
existing 'skip' 'replace' 'merge' 'skip'

See: User Context.