React Native WebGPU

Canvas

The Canvas component, its props and its Android rendering options.

Canvas follows the semantics of the Web <canvas> element: getContext("webgpu") returns the GPUCanvasContext, and the size, pixel density and resize model are the same, so browser WebGPU code largely carries over. The main difference is that you call present() yourself after submitting your commands. The Canvas guide walks through a complete example.

Props

PropTypeDescription
androidAndroidCanvasPropsAndroid-only rendering options: the native view behind the canvas (backingView) and its options (opaque, zOrderOnTop, zOrderMediaOverlay), see Android rendering options. Ignored on iOS and web
colorSpacePredefinedColorSpace"srgb" (the default) or "display-p3", as in configure(). Read when the canvas mounts on iOS and macOS, see Color space and HDR. Ignored on Android and web
toneMappingGPUCanvasToneMapping{ mode: "standard" } (the default) or { mode: "extended" }, as in configure(). Read when the canvas mounts on iOS and macOS, see Color space and HDR. Ignored on Android and web
...ViewPropsViewPropsAll standard React Native View props (style, onLayout, etc.)

Usage

const  = <CanvasRef>(null);

// Once laid out: ref.current.getContext("webgpu")
< ={} ={{ : 1 }} />;

Presenting frames

Call context.present() after every device.queue.submit() to display the frame. It is not part of the WebGPU spec, runs synchronously on the calling thread, and works the same on the main JS runtime, the UI thread and worklet runtimes. See Frame presentations.

Pixel density

clientWidth / clientHeight are the layout size in points, width / height the drawing-buffer size in pixels, which is not scaled to the pixel ratio by default. See Pixel density.

Transparency

alphaMode: "premultiplied" and a clear alpha of 0 show the views behind the canvas on iOS and the web. On Android, alphaMode is ignored: the backing view decides (see Android rendering options). See Transparency.

Color space and HDR

The colorSpace and toneMapping props are read when the canvas mounts on iOS and macOS: pass the same values as to configure(). A change on a mounted canvas is ignored, with a warning in development; remount the canvas with a new key to change them. Android ignores both for now. See Color space and HDR.

Android rendering options

On Android, Canvas can be backed by one of three native views, with different trade-offs between speed and how well the canvas composites with the views around it. The android prop names it, along with its options; it is ignored on iOS and web.

OptionTypeEffect
backingView"TextureView" | "SurfaceView" | "HardwareBufferView"The native view behind the canvas. Defaults to TextureView
opaquebooleanDeclares that the canvas covers every pixel of its bounds, so it is composited without blending. Defaults to false on a TextureView and to true on a SurfaceView; a HardwareBufferView always composites with alpha. Applied in place
zOrderOnTopbooleanSurfaceView only: draws the canvas above every React Native view in the window. Defaults to false
zOrderMediaOverlaybooleanSurfaceView only: draws the canvas above the other SurfaceViews below the window (video players, other canvases). Defaults to false; zOrderOnTop takes precedence
TextureViewSurfaceViewHardwareBufferView
Minimum Android8 (API 26)8 (API 26)10 (API 29)
Behaves like a regular viewyesnoyes
Latencyhighestlowestin between
Opaque by defaultnoyesnever
Statusdefaultopt-inexperimental, opt-in

TextureView is the default: a regular view, so transforms, clipping, alpha and z-order all apply, and the canvas can be composited over other React Native views. The cost is an extra copy, typically a frame of latency, and occasional stalls during some view animations. On Android 10 it always blends, whatever opaque says.

SurfaceView is the fastest option. It is not regular view content, though: parent transforms, clipping, rounded corners and z-ordering with sibling views do not apply to it. Use it for a canvas that is a plain rectangle: a full-screen scene or a game. It is opaque unless asked otherwise: a translucent SurfaceView blends against the window background (usually black) instead of the React Native views beneath it, which are punched out. Pair it with zOrderOnTop to composite over React Native content, and note that zOrderOnTop draws above all React Native views in the window, including navigation screens, regardless of zIndex.

HardwareBufferView composites like a TextureView, with lower latency. It is experimental: if the device cannot allocate the buffers the canvas shows nothing instead of falling back, and some devices may show a stale or torn frame. Test it on your target devices, and drop the backingView to go back to TextureView. Below Android 10 it uses a TextureView, with a warning in development.

The backing view is created when the canvas mounts and kept while it is mounted. opaque applies in place, and so do the z-order options on Android 11 and later; a change of backingView is ignored, with a warning in development. To switch backing views, remount the canvas with a key. The remount leaves the canvas off screen for a frame or two, showing what is behind it, or black, until the new view draws its first frame: the old view leaves and the new one arrives in different window frames.

// The backing view is chosen at mount: a canvas that switches it remounts
<Canvas key={backingView} android={{ backingView }} />

Some combinations for other trade-offs:

// Opaque TextureView: stays in stacking order, e.g. inside a ScrollView
<Canvas android={{ opaque: true }} />

// Full-screen scene on a SurfaceView: no composition pass
<Canvas android={{ backingView: "SurfaceView" }} />

// Translucent SurfaceView above every React Native view
<Canvas android={{ backingView: "SurfaceView", opaque: false, zOrderOnTop: true }} />

// Translucent HardwareBufferView, opt-in (uses a TextureView before Android 10)
<Canvas android={{ backingView: "HardwareBufferView" }} />

See also