FragCanvas Reference

This is the complete prop reference for the

FragCanvas

Svelte component — the main entry point for using MotionGPU.

Import

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

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

Usage

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

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

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 colour applied before the base pass.
`outputColorSpace`	`'srgb'` \| `'linear'`	`'srgb'`	Canvas output colour 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`	`RenderPass[]`	`[]`	Ordered array of post-process passes. See Render Passes.
`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<[report]>`	`undefined`	Custom error renderer snippet. When set, replaces the default `MotionGPUErrorOverlay` .
`onError`	`(report) => void`	`undefined`	Error callback. Called regardless of overlay state. See Error Handling for report shape.

Styling and children

Prop	Type	Default	Description
`class`	`string`	`''`	CSS class applied directly to the `<canvas>` .
`style`	`string`	`''`	Inline styles applied directly to the `<canvas>` .
`children`	`Snippet`	`undefined`	Svelte snippet children. Rendered inside the `FragCanvas` context — this is where `useFrame` , `useMotionGPU` , 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)}
  class="my-canvas-container"
  style="border-radius: 12px; overflow: hidden;"
>
  <Runtime />
</FragCanvas>

<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)}
  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}

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