React Native WebGPU

Canvas

Render your first pixels.

The Canvas component is where you can access a WebGPU context and render pixels. The API is symmetric with its Web counterpart, with a few differences. For instance on React Native you must call context.present() after every device.queue.submit() to present the frame to the screen.

On Android, the canvas is backed by a regular view by default. The Android rendering options explain the trade-offs and how to pick a faster one.

Web conceptReact Native WebGPU
<canvas> in HTML<Canvas> view
canvas.getContext("webgpu")ref.current.getContext("webgpu")
Browser presents framesYou call context.present() after submit

Your first triangle

Mount a Canvas, keep a ref, and draw once the device is ready and the view is laid out:

import { ,  } from "react";
import { , ,  } from "react-native";
import {
  ,
  ,
  ,
  ,
  type CanvasRef,
} from "react-native-webgpu";

const  = `
@vertex fn main(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
  var pos = array<vec2f, 3>(vec2(0, 0.5), vec2(-0.5, -0.5), vec2(0.5, -0.5));
  return vec4f(pos[i], 0.0, 1.0);
}`;

const  = `@fragment fn main() -> @location(0) vec4f {
  return vec4(1.0, 0.0, 0.0, 1.0);
}`;

export function () {
  const  = <CanvasRef>(null);
  const {  } = ();

  (() => {
    if (!) return;

    let  = false;
    let  = 0;

    const  = () => {
      const  = .?.("webgpu");
      if (! || ) {
         = ();
        return;
      }

      const  = . as HTMLCanvasElement;
      if (. === 0 || . === 0) {
         = ();
        return;
      }

      const  = ..();
      . = . * .();
      . = . * .();
      .({ , , : "premultiplied" });

      const  = .({
        : "auto",
        : {
          : .({ :  }),
          : "main",
        },
        : {
          : .({ :  }),
          : "main",
          : [{  }],
        },
        : { : "triangle-list" },
      });

      const  = () => {
        if () return;

        const  = .();
        const  = .({
          : [{
            : .().(),
            : [0, 0, 0, 0],
            : "clear",
            : "store",
          }],
        });
        .();
        .(3);
        .();

        ..([.()]);
        .();
         = ();
      };

       = ();
    };

     = ();

    return () => {
       = true;
      ();
    };
  }, []);

  return (
    < ={{ : 1 }}>
      < ={{ : 1, : "#3498db" }} />
      < ={} ={.} />
    </>
  );
}

The steps, in order:

  1. Mount <Canvas ref={ref} />, and wait for its layout (a non-zero clientWidth and clientHeight).
  2. Request a device, here with useDevice.
  3. Get the context with ref.current.getContext("webgpu"), size its drawing buffer, and configure() it.
  4. For each frame: encode the passes, device.queue.submit(), then context.present().

getContext("webgpu") is synchronous, like on the web. If the canvas is not laid out yet (no context, or a zero clientWidth), retry on the next frame, as the example does.

Frame presentations

On the Web, the browser swaps your rendered frame to the screen automatically when you submit GPU commands. In React Native there is no automatic swap: presentation is a manual step. After you submit your commands to the queue, call present() on the context to display the frame.

..([.()]);
.(); // React Native only

present() is a React Native only method (it is not part of the Web WebGPU spec). It runs synchronously on the calling thread, so the frame is presented from whichever thread did the rendering. This works the same on every runtime: the main JS runtime, the UI thread, and dedicated worklet runtimes. Always call it after submit(), never before.

Your loop sets the frame rate. React Native's global requestAnimationFrame drops frames on a high refresh rate display: it runs at 60 Hz on iOS, falls to 60 fps on Android once a frame takes more than about 6 ms of JavaScript, and polls every 16 ms on a worklet runtime of your own. Use the requestAnimationFrame of react-native-webgpu instead: it follows the display on every runtime, up to 120 Hz. An app created from an Expo or React Native template before React Native 0.82 may still carry iOS's 60 Hz cap for iPhone: Reanimated's performance guide covers the Info.plist opt-in.

Pixel density

Just like on the Web, a canvas has two independent sizes:

  • clientWidth / clientHeight are the on-screen (layout) size in logical points. They follow the view's layout and update automatically when it resizes.
  • width / height are the drawing-buffer size in physical pixels. This is the resolution WebGPU actually renders at.

The drawing buffer is not scaled to the device pixel ratio by default, exactly as on the Web. To render crisply on high-density screens, set the buffer size to the layout size multiplied by the pixel ratio. PixelRatio.get() is the React Native equivalent of window.devicePixelRatio.

const  = . as HTMLCanvasElement;
. = . * .();
. = . * .();

Because clientWidth / clientHeight track layout, recompute the buffer size whenever they change (for example on rotation or a resize).

Transparency

To render the canvas over the React Native views beneath it, configure the context with alphaMode: "premultiplied" and clear with a color whose alpha is 0, so that WebGPU produces a transparent frame:

.({ , , : "premultiplied" });

const  = .({
  : [
    {
      : .().(),
      : [0, 0, 0, 0], // transparent
      : "clear",
      : "store",
    },
  ],
});

Platform note

On iOS alphaMode alone controls it. On Android the alphaMode passed to configure() is ignored: the backing view decides, and the default TextureView composites with alpha unless android={{ opaque: true }} asks it not to, while a SurfaceView is opaque unless asked otherwise. See the Android rendering options.

Color space

By default the canvas's values are sRGB. Pass colorSpace: "display-p3" to configure() to write Display P3 values instead, as you would in a browser; both use the sRGB transfer function. On iOS and macOS, also pass it to the Canvas: the color space is set when the canvas mounts, so colors outside sRGB show on a wide-gamut display and match other Display P3 content, such as a Skia canvas. Android ignores it for now.

<Canvas ref={ref} colorSpace="display-p3" style={{ flex: 1 }} />;

context.configure({ device, format, colorSpace: "display-p3" });

The Canvas props are read once, when it mounts: a change on a mounted canvas is ignored, with a warning in development. To change them, remount the canvas with a new key. If configure() asks for something else than the canvas was mounted with, a warning says so in development.

HDR

On an rgba16float canvas, values above 1.0 are clamped to the display's SDR range by default. Pass toneMapping: { mode: "extended" } to configure() to let them use the display's extended range (HDR) instead, as in a browser. On iOS 16 and later and on macOS, also pass it to the Canvas, which reads it when it mounts, like colorSpace. The mode has no effect on an 8-bit canvas, and tvOS and Android ignore it for now.

<Canvas ref={ref} toneMapping={{ mode: "extended" }} style={{ flex: 1 }} />;

context.configure({
  device,
  format: "rgba16float",
  toneMapping: { mode: "extended" },
});

See also