@typegpu/react

Setting up and managing TypeGPU resources in React components is not a trivial task, which is why we provide a set of hooks and utilities to help with it.

Setup

Refer to TypeGPU’s installation guide for setting up TypeGPU if you haven’t already. After that, install React and @typegpu/react using the package manager of your choice.

npm

npm install @typegpu/react

pnpm

pnpm add @typegpu/react

yarn

yarn add @typegpu/react

Your first effect

We first get a reference to a TypeGPU root via the useRoot hook.

import { useRoot } from '@typegpu/react';

function MyEffect() {
  const root = useRoot();

  // the rest of our code will be here
}

Then we create a Render Pipeline that emits a red color over the whole canvas, and we memoize it.

const renderPipeline = useMemo(
  () =>
    root.createRenderPipeline({
      vertex: common.fullScreenTriangle,
      fragment: () => {
        'use gpu';
        //             r  g  b  a
        return d.vec4f(1, 0, 0, 1);
      },
    }),
  [root],
);

We need to update our imports to get access to both d and common from typegpu:

import { d, common } from 'typegpu';

Then we call the useConfigureContext hook, which will give us a ref to pass into a <canvas> element, as well as access to the WebGPU context via ctxRef.

  // ...
  const { ref, ctxRef } = useConfigureContext();

  return <canvas ref={ref} className="absolute inset-0" />;
}

We’ll draw to the canvas each frame using useFrame:

useFrame(() => {
  if (!ctxRef.current) return;

  renderPipeline
    .withColorAttachment({ view: ctxRef.current })
    .draw(3); // 3 vertices of the full-screen triangle
});

After these changes, you should see a blank red canvas on your webpage. Let’s make the effect more interesting.

Pixel variance

Right now, each pixel is calculating exactly the same value, which is why we get a single color output. The fragment function received contextual information as an argument, and can use it to vary the output along the image.

const renderPipeline = useMemo(
  () =>
    root.createRenderPipeline({
      vertex: common.fullScreenTriangle,
      fragment: () => {
      fragment: ({ uv }) => {
        'use gpu';
        //             r  g  b  a
        return d.vec4f(1, 0, 0, 1);
        return d.vec4f(uv, 0, 1);
      },
    }),
  [root],
);

The uv value is a 2d vector provided by the vertex shader common.fullScreenTriangle, and ranges from 0 to 1 in both axes. Since it consists of x and y components, it can be placed inside the d.vec4f() constructor and fills up the red and green channels.

Dynamic values

To pass dynamic values to your shader without having to recompile it (compilation takes significant time), you can use useUniform or useMirroredUniform, depending on the situation.

• useUniform - allocates a uniform that can be updated outside of the React lifecycle.
• useMirroredUniform - allocates a uniform and keeps it synchronized with the latest value.

We’re going to define a time variable to use in our shader. Since it’s a value that will get updated each frame, we want it to be done outside of the React lifecycle to not trigger deadly re-renders. Let’s choose useUniform:

const root = useRoot();
const time = useUniform(d.f32);

const renderPipeline = useMemo(
  () =>
    root.createRenderPipeline({
    vertex: common.fullScreenTriangle,
      fragment: ({ uv }) => {
        'use gpu';
        return d.vec4f(uv, 0, 1);
        return d.vec4f((uv * 5 + time.$) % 1, 0, 1);
      },
    }),
  [root, time],
);

We have just tiled the pattern with multiplication and modulo, but since we’re not updating time, it’s a still image.

We can update time each frame to get the desired result:

useFrame(() => {
useFrame(({ elapsedSeconds }) => {
  if (!ctxRef.current) return;

  time.write(elapsedSeconds);

  renderPipeline.withColorAttachment({ view: ctxRef.current }).draw(3);
});

Complete example

import { useMemo } from 'react';
import { d, common } from 'typegpu';
import { useConfigureContext, useFrame, useRoot, useUniform } from '@typegpu/react';

function MyEffect() {
  const root = useRoot();
  const time = useUniform(d.f32);

  const renderPipeline = useMemo(
    () =>
      root.createRenderPipeline({
        vertex: common.fullScreenTriangle,
        fragment: ({ uv }) => {
          'use gpu';
          return d.vec4f((uv * 5 + time.$) % 1, 0, 1);
        },
      }),
    [root, time],
  );

  const { ref, ctxRef } = useConfigureContext();
  useFrame(({ elapsedSeconds }) => {
    if (!ctxRef.current) return;

    time.write(elapsedSeconds);

    renderPipeline.withColorAttachment({ view: ctxRef.current }).draw(3);
  });

  return <canvas ref={ref} className="absolute inset-0" />;
}

API Reference

useRoot

Returns the TypeGPU root shared between all components under the nearest <Root> provider. (equivalent to calling await tgpu.init()).

It’s not necessary to use a <Root> provider; if none is found, the global root is used instead.

import { useRoot } from '@typegpu/react';

function MyEffect() {
  const root = useRoot();

  // ...
}

If the root hasn’t been initialized yet, it will suspend the component until it is. This hook will also throw if there is an error initializing the root (like no WebGPU support). If you’d like to handle these cases yourself, you can use useRootOrError or useRootWithStatus instead.

useUniform

const foo = useUniform(schema, { /* options */ });

Option	Description
initial	An initial value given to the uniform buffer on component mount. Alternatively, a function can be passed in to imperatively write to the buffer while its still mapped to CPU memory.
onInit	A function that will be called after the buffer is initialized. An example of where this is useful is populating the buffer with a compute shader.

// creating a resource to be updated outside of the React lifecycle
const time = useUniform(d.f32);

const updateTime = useCallback((value: number) => {
  time.write(value);
}, [time]);

useMutable

const foo = useMutable(schema, { /* options */ });

Option	Description
initial	An initial value given to the mutable buffer on component mount. Alternatively, a function can be passed in to imperatively write to the buffer while its still mapped to CPU memory.
onInit	A function that will be called after the buffer is initialized. An example of where this is useful is populating the buffer with a compute shader.

// creating a mutable resource to be updated outside of the React lifecycle
const counter = useMutable(d.f32);

// a compute shader that increments the counter in-place
const incrementPipeline = useMemo(() => {
  return root.createGuardedComputePipeline(() => {
    'use gpu';
    // Direct memory access through .$
    counter.$ += 1;
  });
}, [root, counter]);

// a function that dispatches the shader and reads the result asynchronously
const increment = useEffectEvent(async (value: number) => {
  incrementPipeline.dispatchThreads();
  return await counter.read();
});

useReadonly

const foo = useReadonly(schema, { /* options */ });

Option	Description
initial	An initial value given to the readonly buffer on component mount. Alternatively, a function can be passed in to imperatively write to the buffer while its still mapped to CPU memory.
onInit	A function that will be called after the buffer is initialized. An example of where this is useful is populating the buffer with a compute shader.

useMirroredUniform

const foo = useMirroredUniform(schema, valueToMirror);

On each React re-render, the uniform will be updated with the latest value of valueToMirror.

// a value accessible in the React lifecycle
const theme = useTheme();

// making it accessible in a shader
const primaryColor = useMirroredUniform(d.vec3f, d.vec3f(...theme.primaryColor));

// ...

useBindGroup

const group = useBindGroup(layout, { /* entries */ });

Creates a bind group out of the given resources. The API matches root.createBindGroup.

The <Root> component

The <Root> component is a context provider for all of its descendants. All useRoot calls made by components beneath this wrapper will return the same TgpuRoot object.

Property	Type	Description
root	TgpuRoot|undefined	A custom root to provide for all descendants. If not provided, one will be created on demand.

import { Root } from '@typegpu/react';

function App() {
  return (
    <Root>
      {/* ... other components ... */}
    </Root>
  );
}