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
| Prop | Type | Description |
|---|---|---|
android | AndroidCanvasProps | Android-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 |
colorSpace | PredefinedColorSpace | "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 |
toneMapping | GPUCanvasToneMapping | { 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 |
...ViewProps | ViewProps | All 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.
| Option | Type | Effect |
|---|---|---|
backingView | "TextureView" | "SurfaceView" | "HardwareBufferView" | The native view behind the canvas. Defaults to TextureView |
opaque | boolean | Declares 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 |
zOrderOnTop | boolean | SurfaceView only: draws the canvas above every React Native view in the window. Defaults to false |
zOrderMediaOverlay | boolean | SurfaceView only: draws the canvas above the other SurfaceViews below the window (video players, other canvases). Defaults to false; zOrderOnTop takes precedence |
TextureView | SurfaceView | HardwareBufferView | |
|---|---|---|---|
| Minimum Android | 8 (API 26) | 8 (API 26) | 10 (API 29) |
| Behaves like a regular view | yes | no | yes |
| Latency | highest | lowest | in between |
| Opaque by default | no | yes | never |
| Status | default | opt-in | experimental, 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
- Canvas guide: a complete example, the frame loop, pixel density and transparency
- GPUDeviceProvider: share one device across components
- Learn WebGPU: tutorials for the low-level API