Choose settings based on the host application, terminal count, and accessibility requirements.
const terminal = await createTerminal({
container,
worker: 'dedicated',
renderer: 'auto',
scrollbackLines: 10_000,
accessibility: 'basic',
});
These values match the default behavior, so omit them unless being explicit helps your integration.
| Value | Behavior | Good fit |
|---|---|---|
true or 'dedicated' |
One worker per terminal when supported | One terminal or strong session isolation |
'shared' |
Multiple terminal sessions multiplexed through one worker | Terminal-heavy views where worker count matters |
false |
Parse and render on the main thread | Tests, constrained embeds, or unsupported worker environments |
The default behaves like 'dedicated' when Worker and OffscreenCanvas are available, with a
main-thread fallback. A shared worker reduces worker overhead, but one busy session can share an
event loop with the others.
'auto' is the recommended default. It attempts WebGPU, then WebGL2, then Canvas 2D. An explicit
'webgpu' request fails if WebGPU cannot initialize. An explicit 'webgl2' request uses Canvas 2D
when WebGL2 is unavailable. Read terminal.renderer.backend to report or measure the selected path.
The GPU backends accelerate cell backgrounds and decorations. Browser Canvas 2D still shapes text, which preserves web-font flexibility and avoids a separate glyph atlas contract.
Browser terminals measure their grid from the container unless cols and rows are supplied. With
a fixed grid, automatic observer-driven resize keeps that grid size. Calling fit() explicitly
remeasures the host even when initial dimensions were configured.
The default scrollback limit is 10,000 lines. Lower it for many concurrent terminals or memory-tight devices. Increase it only when the product requires more history and after measuring memory and viewport operations with representative output.
cellWidthPx and cellHeightPx are useful for headless terminals. Browser cell size is derived from
the active font, line height, letter spacing, and device pixel ratio.
| Value | Behavior |
|---|---|
'off' |
No viewport mirror |
'basic' |
Accessible terminal/input semantics without a mirrored viewport |
'full' |
Adds a live viewport text mirror for assistive technology |
'basic' is the default. Full accessibility transfers and updates visible text from the worker, so
test its cost with realistic output. Use 'full' when the product requires the live text mirror.
allowTransparency is false by default and must be chosen before renderer initialization. When
enabled, Canvas2D, WebGL2, and WebGPU all preserve theme alpha. minimumContrastRatio defaults to
1; increase it when the product needs automatic foreground adjustment. See
Theming for examples and constraints.
Most bundlers, including Vite, can use the package-derived default WASM URLs without configuration.
Provide wasm and callbacksWasm only when assets are self-hosted, embedded as bytes, precompiled,
or served from a custom path.
Pin and cache the two compatible artifacts together. The package validates Ghostty's self-described ABI before creating a runtime.