FragCanvas Reference

This is the complete prop reference for FragCanvas — the main adapter entrypoint for using Motion GPU in Svelte, React, and Vue.

Import

import { FragCanvas } from '@motion-core/motion-gpu/svelte';

Usage

<FragCanvas
  material={myMaterial}
  clearColor={[0, 0, 0, 1]}
  outputColorSpace="srgb"
  renderMode="always"
  passes={[vignettePass]}
  onError={handleError}
>
  <Runtime />
</FragCanvas>

Adapter-specific naming differences (class vs className vs canvasClass, style type, children/slots) are listed below.

Props

Required

Prop	Type	Description
`material`	`FragMaterial`	The material to render. Must be created with `defineMaterial()`.

Rendering

Prop	Type	Default	Description
`clearColor`	`[number, number, number, number]`	`[0, 0, 0, 1]`	RGBA clear color applied before the base pass.
`outputColorSpace`	`'srgb'` \| `'linear'`	`'srgb'`	Canvas output color space. Changing triggers renderer rebuild.
`renderMode`	`'always'` \| `'on-demand'` \| `'manual'`	`'always'`	Controls frame rendering frequency.
`autoRender`	`boolean`	`true`	Hard gate — when `false`, no rendering occurs regardless of render mode.
`maxDelta`	`number`	`0.1`	Maximum frame delta in seconds (clamps `state.delta`). Must be `> 0`.
`dpr`	`number`	`devicePixelRatio` (or `1` during SSR)	Device pixel ratio for resolution scaling.

Post-processing

Prop	Type	Default	Description
`passes`	`AnyPass[]`	`[]`	Ordered array of render and compute passes. See Render Passes and Compute Shaders.
`renderTargets`	`RenderTargetDefinitionMap`	`{}`	Named off-screen render targets. See Render Targets.

WebGPU configuration

Prop	Type	Default	Description
`adapterOptions`	`GPURequestAdapterOptions`	`undefined`	Forwarded to `navigator.gpu.requestAdapter()`. Can specify `powerPreference`, `forceFallbackAdapter`, etc.
`deviceDescriptor`	`GPUDeviceDescriptor`	`undefined`	Forwarded to `adapter.requestDevice()`. Can request specific features or limits.

Error handling

Prop	Type	Default	Description
`showErrorOverlay`	`boolean`	`true`	Enables error UI rendering (`errorRenderer` or default overlay).
`errorRenderer`	`Snippet<[MotionGPUErrorReport]>` (Svelte) / `(report: MotionGPUErrorReport) => ReactNode` (React) / scoped slot `#errorRenderer="{ report }"` (Vue)	`undefined`	Custom error renderer. When set, replaces the default `MotionGPUErrorOverlay`.
`onError`	`(report: MotionGPUErrorReport) => void`	`undefined`	Error callback. Called regardless of overlay state. See Error Handling for report shape.
`errorHistoryLimit`	`number`	`0`	Enables bounded error history when `> 0`; values are normalized with `Math.floor`.
`onErrorHistory`	`(history: MotionGPUErrorReport[]) => void`	`undefined`	Callback with deduplicated ring-buffer history snapshots.

Error history behavior

History is disabled when errorHistoryLimit <= 0.
History stores the latest N reports when errorHistoryLimit > 0.
Consecutive identical reports are deduplicated (phase/title/message/rawMessage key).
Reducing errorHistoryLimit trims existing history immediately.

Styling and children

Prop	Type	Default	Description
`class` (Svelte) / `className` (React) / `canvasClass` (Vue)	`string`	`''`	CSS class applied directly to the `<canvas>`.
`style` (Svelte/React) / `canvasStyle` (Vue)	`string` (Svelte) / `React.CSSProperties` (React) / `string` `Record<string, string` `number>` (Vue)	`''` (Svelte) / `undefined` (React/Vue)	Inline styles applied directly to the `<canvas>`.
`children` (Svelte/React) / default slot (Vue)	`Snippet` (Svelte) / `ReactNode` (React) / slot (Vue)	`undefined`	Children rendered inside the `FragCanvas` context — this is where `useFrame`, `useMotionGPU`, `usePointer`, etc. work.

Lifecycle

Phase	What happens
Mount	Frame registry and context created. Material resolved. Pipeline signature computed. Renderer created (async). RAF loop started.
Frame	Timing computed. Size updated. Scheduler tasks run. Render gate evaluated. If open: uniforms merged, textures uploaded, passes executed, frame presented.
Signature change	Old renderer destroyed. New renderer created with updated signature. Exponential backoff on failure.
Destroy	RAF cancelled. Renderer destroyed (GPU resources freed). Scheduler cleared.

Canvas sizing

FragCanvas renders a <canvas> inside a container <div>. The canvas fills its container using width: 100%; height: 100% CSS. The container determines the effective canvas dimensions.

The physical size (GPU resolution) is containerSize × dpr.

Example: full configuration

<FragCanvas
  material={material}
  clearColor={[0.05, 0.05, 0.1, 1]}
  outputColorSpace="srgb"
  renderMode="on-demand"
  autoRender={true}
  maxDelta={0.05}
  dpr={2}
  passes={[tonePass, vignettePass]}
  renderTargets={{ halfRes: { scale: 0.5 } }}
  adapterOptions={{ powerPreference: 'high-performance' }}
  showErrorOverlay={true}
  errorRenderer={myErrorRenderer}
  onError={(report) => sendToTelemetry(report)}
  errorHistoryLimit={20}
  onErrorHistory={(history) => sendErrorHistory(history)}
  class="my-canvas-container"
  style="border-radius: 12px; overflow: hidden;"
>
  <Runtime />
</FragCanvas>

{#snippet myErrorRenderer(report)}
  <aside class="my-error-banner">
    <strong>{report.title}</strong>
    <p>{report.message}</p>
  </aside>
{/snippet}