Renderers and fallbacks

You will know which renderer opened and how to choose a fallback. Start with the main entry and a sized host.

1. Let the terminal choose

renderers.ts

import { Terminal } from 'ghostty-webgpu'

export async function mountRenderer(host: HTMLElement) {
  const terminal = await Terminal.create({ rendererMode: 'auto' })
  await terminal.open(host)
  terminal.writeln(`Renderer: ${terminal.diagnostics.rendererBackend}`)
  return () => terminal.dispose()
}

On desktop Linux, the main entry tries WebGL2, hardware WebGPU, Canvas 2D, then DOM. On macOS, Windows, Android, ChromeOS, and other platforms, it tries hardware WebGPU before WebGL2. A capability failure advances to the next backend. diagnostics.rendererBackend reports the selected backend after open.

2. Choose Canvas 2D explicitly

Set rendererMode to canvas2d-fill-text when creating the main-thread terminal. The public mode option accepts auto, canvas2d-fill-text and canvas2d-pixels. The pixel compositor is experimental. Use fill-text for a Canvas integration.

For a GPU-specific integration, rendererFactory lets the host supply a renderer. rendererMode: 'webgpu' and rendererMode: 'webgl2' are outside this option’s type. The worker entry has a separate backend option with auto, webgpu and webgl.

3. Check the result

All four backends read Ghostty’s terminal state. Font availability and browser capabilities can change appearance. Measure the workload on the backend your users will run. The benchmark report keeps renderer comparisons and limitations together.

If it doesn’t work

WebGPU is unavailable

Use a secure context and a current browser with a usable GPU adapter. The default main entry falls back automatically. A forced backend or worker operation may return a capability error. Keep its code, why and fix when displaying it to the user.

Many terminals lose WebGL contexts

Browsers impose context limits. Dispose terminals you remove and bound the number of simultaneously live terminals. Test your intended count on your target browser. The main entry follows the remaining backend order after context loss, including hardware WebGPU when Linux selected WebGL2 first.

Next, load your fonts before comparing cell geometry.