# API overview (https://blode.co/react-vello/docs/api/overview)

Core exports — createVelloRoot, Canvas, Rect, and Text.

This page covers the main public surface from `react-vello`. Types live in the package; the shapes below match the published TypeScript definitions.

## `createVelloRoot`

Mount a React Vello tree on an existing `<canvas>`.

```ts
function createVelloRoot(
  canvas: HTMLCanvasElement,
  options?: RendererOptions
): VelloRoot;
```

### `RendererOptions`

| Option | Type | Description |
| --- | --- | --- |
| `onReady` | `(context: CanvasContext) => void` | Called when the renderer is ready (GPU or fallback). |
| `onFrame` | `(ops: Uint8Array) => void` | Encoded frame buffer; valid only for the duration of the call. |
| `onError` | `(error: unknown) => void` | WebGPU / WASM init failure. |
| `debug` | `boolean` | Collect per-stage timings for `getStats()`. Off by default. |

### `VelloRoot`

| Method | Description |
| --- | --- |
| `render(children)` | Reconcile and draw a React tree. |
| `unmount()` | Clear the container and stop rendering. |
| `getContext()` | Access `canvas`, `backend`, `requestFrame`, and `getStats`. |

```tsx
import { Canvas, Rect, createVelloRoot } from "react-vello";

const root = createVelloRoot(canvas, {
  onReady: (ctx) => console.log(ctx.backend),
  onError: (error) => console.error(error),
});

root.render(
  <Canvas width={640} height={360}>
    <Rect origin={[0, 0]} size={[100, 100]} fill={{ kind: "solid", color: "#000" }} />
  </Canvas>
);
```

## `Canvas`

Root scene node. Sets presentation size and canvas attributes.

| Prop | Type | Description |
| --- | --- | --- |
| `width` / `height` | `number` | Presentation size in CSS pixels. |
| `autoSize` | `boolean` | Size from the canvas element / container. |
| `devicePixelRatio` | `number` | Override DPR. |
| `backgroundColor` | `string \| RgbaColor` | Clear color. |
| `colorSpace` | `"srgb" \| "display-p3"` | Color space hint. |
| `antialiasing` | `"fast" \| "msaa" \| "none"` | AA mode. |
| `onReady` / `onError` | callbacks | Scene-level ready / error hooks. |
| `children` | `ReactNode` | Scene nodes (`Rect`, `Text`, …). |

Also accepts common DOM-ish props: `className`, `style`, `tabIndex`, `role`, `title`, `ariaLabel`.

## `Rect`

Axis-aligned rectangle with optional rounded corners.

| Prop | Type | Description |
| --- | --- | --- |
| `origin` | `[x, y]` | Top-left corner. |
| `size` | `[width, height]` | Extent. |
| `width` / `height` | `number` | Alternate size shorthands. |
| `radius` | `number \| Vec2 \| corners` | Corner radius. |
| `fill` | `Paint` | Fill paint (`{ kind: "solid", color }`, …). |
| `stroke` | `Stroke` | Stroke width, paint, join, cap, dash. |

Inherits shared node props: `opacity`, `transform` / `x` / `y` / `rotation` / `scaleX` / `scaleY`, pointer and drag handlers, `visible`, `listening`, `draggable`, and more.

## `Text`

GPU-friendly text run.

| Prop | Type | Description |
| --- | --- | --- |
| `children` / `text` | `ReactNode` / `string` | Content to draw. |
| `origin` | `[x, y]` | Baseline origin. |
| `font` | `TextFont` | `family`, `size`, optional `weight`, `style`, `lineHeight`. |
| `fill` | `Paint` | Text color / paint. |
| `maxWidth` | `number` | Wrap width. |
| `align` | `"start" \| "center" \| "end"` | Horizontal alignment. |

```tsx
<Text
  origin={[24, 48]}
  font={{ family: "Inter", size: 18, weight: 500 }}
  fill={{ kind: "solid", color: "#0f172a" }}
>
  Hello Vello
</Text>
```

## Other host components

Also exported: `Group`, `Path`, `Image`, `LinearGradient`, `RadialGradient`, `Mask`, `ClipPath`. See the TypeScript types in `react-vello` for full prop lists.

# Introduction (https://blode.co/react-vello/docs)

A React renderer powered by Vello — Rust GPU rendering via WASM and WebGPU.

Draw shapes and text declaratively in React while Rust handles the rendering. React Vello is a custom React reconciler backed by [Vello](https://github.com/linebender/vello), compiled to WASM and drawn with WebGPU.

## Why React Vello

- **Declarative scene graph** — compose `Canvas`, `Rect`, `Text`, and other host components like any React tree
- **GPU-first** — Vello renders through WebGPU when available
- **WASM included** — the renderer ships with the package; no separate native toolchain
- **Familiar ergonomics** — inspired by [react-three-fiber](https://github.com/pmndrs/react-three-fiber), [react-konva](https://github.com/konvajs/react-konva), and [react-pdf](https://github.com/diegomura/react-pdf)

## Demo

Try the live demo at [blode.co/react-vello](https://blode.co/react-vello).

## Next steps

1. [Install](https://blode.co/react-vello/docs/docs/installation) the package
2. Follow the [quickstart](https://blode.co/react-vello/docs/docs/quickstart)
3. Read [WebGPU notes](https://blode.co/react-vello/docs/docs/webgpu) for browser requirements
4. Browse the [API overview](https://blode.co/react-vello/docs/docs/api/overview)

# Installation (https://blode.co/react-vello/docs/installation)

Install react-vello and its peer dependencies.

## Requirements

- **React** 18 or 19
- **react-dom** (peer dependency)
- A browser with **WebGPU** enabled for the GPU path (see [WebGPU](https://blode.co/react-vello/docs/docs/webgpu))

## Install

```bash
npm install react-vello react react-dom
```

Or with pnpm / yarn / bun:

```bash
pnpm add react-vello react react-dom
```

```bash
yarn add react-vello react react-dom
```

```bash
bun add react-vello react react-dom
```

## What you get

The package includes:

- The React host components (`Canvas`, `Rect`, `Text`, …)
- `createVelloRoot` to mount a scene onto an HTML canvas
- The WASM Vello renderer (no extra install step)

## Next

Continue to the [quickstart](https://blode.co/react-vello/docs/docs/quickstart).

# Quickstart (https://blode.co/react-vello/docs/quickstart)

Mount a Vello scene on a canvas in a few lines of React.

Create an HTML canvas, mount a Vello root, and render a scene.

## HTML

```html
<canvas id="vello"></canvas>
```

## React

```tsx
import { Canvas, Rect, Text, createVelloRoot } from "react-vello";

const canvas = document.querySelector("#vello") as HTMLCanvasElement;
const root = createVelloRoot(canvas);

root.render(
  <Canvas width={640} height={360}>
    <Rect
      origin={[40, 40]}
      size={[200, 120]}
      fill={{ kind: "solid", color: "#3b82f6" }}
      radius={16}
    />
    <Text
      origin={[60, 110]}
      font={{ family: "Space Grotesk", size: 32, weight: 600 }}
      fill={{ kind: "solid", color: "#0f172a" }}
    >
      Hello Vello
    </Text>
  </Canvas>
);
```

## Updating the scene

Call `root.render(...)` again with a new tree whenever props or children change. Use `root.unmount()` to tear down the reconciler and stop rendering.

## Next

- [WebGPU notes](https://blode.co/react-vello/docs/docs/webgpu) — browser support and fallbacks
- [API overview](https://blode.co/react-vello/docs/docs/api/overview) — `Canvas`, `Rect`, `Text`, and `createVelloRoot`

# WebGPU (https://blode.co/react-vello/docs/webgpu)

Browser requirements, the WASM renderer, and the Canvas 2D fallback.

React Vello prefers WebGPU. The WASM Vello renderer is bundled with the package.

## Requirements

- Use a browser with WebGPU enabled (current Chromium-based browsers are the most reliable path).
- Serve your page over a secure context (`https` or `localhost`).

If `navigator.gpu` is missing, the root still mounts. Rendering falls back to a Canvas 2D software path so the scene stays visible while you develop without GPU support.

## How the root chooses a backend

`createVelloRoot` checks for WebGPU at creation time:

1. **WebGPU available** — load WASM, create the GPU renderer, and call `onReady` when the driver is ready.
2. **WebGPU init fails** — disable the GPU driver, switch `backend` to `"canvas"`, and call `onError` then `onReady`.
3. **No WebGPU** — skip WASM init and call `onReady` on a microtask with `backend: "canvas"`.

Inspect the active path with `root.getContext().backend` (`"webgpu"` | `"canvas"`).

## No extra WASM setup

You do not need to configure wasm-pack, copy assets by hand, or register a separate loader for the published package. The renderer ships inside `react-vello` and loads through the package's WASM bridge.

## Tips

- Prefer Chromium for demos and stress tests that exercise the GPU path.
- Pass `onError` to `createVelloRoot` if you want to surface GPU init failures in your UI.
- Pass `debug: true` when you need per-stage frame timings via `getContext().getStats()`.