API Reference

Complete reference for all wterm options, methods, types, and transport APIs.

Terminal Options

Both the React <Terminal> component and the vanilla WTerm constructor accept these options:

Option	Type	Default	Description
`cols`	`number`	`80`	Initial column count
`rows`	`number`	`24`	Initial row count
`wasmUrl`	`string`	—	URL to serve the WASM binary separately. When omitted, the ~12 KB binary is decoded from an inlined base64 string.
`autoResize`	`boolean`	`true` (vanilla) / `false` (React)	Automatically resize the terminal to fit its container using a `ResizeObserver`
`cursorBlink`	`boolean`	`false`	Enable cursor blinking animation
`onData`	`(data: string) => void`	—	Called when the terminal produces data (user input or host response). When omitted, input is echoed back automatically.
`onTitle`	`(title: string) => void`	—	Called when the terminal title changes via an escape sequence
`onResize`	`(cols: number, rows: number) => void`	—	Called after the terminal is resized

React-Only Props

The React <Terminal> component adds these props on top of the shared options above. It also spreads standard HTML attributes (className, style, id, etc.) onto the root div.

Prop	Type	Description
`theme`	`string`	Name of a built-in or custom theme (see Themes)
`onReady`	`(wt: WTerm) => void`	Called with the underlying `WTerm` instance after WASM loads and initialization completes
`onError`	`(error: unknown) => void`	Called if WASM loading or initialization fails. When omitted, errors are logged to the console.

WTerm Methods

Instance methods on the vanilla WTerm class:

Method	Description
`init(): Promise<WTerm>`	Load WASM and start rendering
`write(data: string \| Uint8Array)`	Write data to the terminal
`resize(cols, rows)`	Resize the terminal grid
`focus()`	Focus the terminal input
`destroy()`	Clean up event listeners, observers, and DOM

Imperative Handle (React)

The useTerminal hook returns a ref and convenience methods that delegate to the underlying WTerm instance:

const { ref, write, resize, focus } = useTerminal();

Return	Type	Description
`ref`	`RefObject<TerminalHandle>`	Pass to `<Terminal ref={ref}>`
`write`	`(data: string \| Uint8Array) => void`	Write data to the terminal
`resize`	`(cols: number, rows: number) => void`	Resize the terminal grid
`focus`	`() => void`	Focus the terminal input

The TerminalHandle interface exposed via ref:

interface TerminalHandle {
  write(data: string | Uint8Array): void;
  resize(cols: number, rows: number): void;
  focus(): void;
  readonly instance: WTerm | null;
}

WebSocketTransport

Connect to a PTY backend over WebSocket with automatic reconnection and send buffering.

Options

Option	Type	Default	Description
`url`	`string`	—	WebSocket server URL
`reconnect`	`boolean`	`true`	Automatically reconnect on disconnect with exponential backoff
`maxReconnectDelay`	`number`	`30000`	Maximum delay between reconnection attempts (ms)
`onData`	`(data: Uint8Array \| string) => void`	—	Called when data is received from the server
`onOpen`	`() => void`	—	Called when the connection opens
`onClose`	`() => void`	—	Called when the connection closes
`onError`	`(event: Event) => void`	—	Called when a WebSocket error occurs

Methods

Method	Description
`connect(url?)`	Open the WebSocket connection. Optionally override the URL.
`send(data: string \| Uint8Array)`	Send data to the server. If the socket is not yet open, data is buffered and flushed on connect.
`close()`	Close the connection and stop reconnection attempts.

Properties

Property	Type	Description
`connected`	`boolean`	Whether the WebSocket is currently open

WasmBridge

Low-level interface to the Zig/WASM terminal state machine. The bridge manages a virtual terminal grid in WASM memory — you write data in and read cells, cursor state, and scrollback out.

Loading

import { WasmBridge } from "@wterm/core";

const bridge = await WasmBridge.load();
const bridge = await WasmBridge.load("/wterm.wasm");

When no URL is provided, the ~12 KB WASM binary is decoded from a base64 string inlined in the package. Pass a URL when you want to serve the binary separately for caching or CDN use.

Methods

Method	Description
`WasmBridge.load(url?): Promise<WasmBridge>`	Load the WASM binary and return a new bridge instance
`init(cols, rows)`	Initialize the terminal grid
`writeString(str)`	Write a UTF-8 string (including escape sequences) to the terminal
`writeRaw(data: Uint8Array)`	Write raw bytes to the terminal (chunked to 8192 bytes internally)
`resize(cols, rows)`	Resize the terminal grid
`getCell(row, col): CellData`	Get cell data at a grid position
`getCursor(): CursorState`	Get current cursor position and visibility
`getCols() / getRows()`	Get current grid dimensions
`isDirtyRow(row): boolean`	Check if a row has changed since last `clearDirty()`
`clearDirty()`	Reset all dirty-row flags
`getTitle(): string \| null`	Get pending title change (via OSC escape), or `null` if unchanged
`getResponse(): string \| null`	Get pending host response (e.g. DSR), or `null`. Reading clears the buffer.
`getScrollbackCount(): number`	Number of lines in the scrollback buffer
`getScrollbackCell(offset, col): CellData`	Get cell data from a scrollback line
`getScrollbackLineLen(offset): number`	Get the length of a scrollback line
`cursorKeysApp(): boolean`	Whether cursor keys are in application mode
`bracketedPaste(): boolean`	Whether bracketed paste mode is active
`usingAltScreen(): boolean`	Whether the alternate screen buffer is active

Types

interface CellData {
  char: number;   // Unicode code point
  fg: number;     // Foreground color index (256 = default)
  bg: number;     // Background color index (256 = default)
  flags: number;  // Style flags (bold, italic, underline, etc.)
}

interface CursorState {
  row: number;
  col: number;
  visible: boolean;
}