page.mdx

API Reference

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

Terminal Options

The React and Vue <Terminal> components and the vanilla WTerm constructor all accept these options:

Option	Type	Default	Description
cols	number	80	Initial column count
rows	number	24	Initial row count
core	TerminalCore	—	A pre-constructed terminal core instance. When provided, wasmUrl is ignored and this core is used instead of loading the built-in Zig WASM binary. See Ghostty Core for an example.
wasmUrl	string	—	URL to serve the WASM binary separately. When omitted, the ~12 KB binary is decoded from an inlined base64 string. Ignored when core is provided.
autoResize	boolean	true (vanilla) / false (React, Vue)	Automatically resize the terminal to fit its container using a ResizeObserver
cursorBlink	boolean	false	Enable cursor blinking animation
debug	boolean	false	Enable debug mode. Exposes a DebugAdapter on the WTerm instance (wt.debug) for inspecting escape sequences, cell data, render performance, and unhandled CSI sequences.
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.

Vue-Only Props

The Vue <Terminal> component adds these props on top of the shared options above. Vue exposes input callbacks as events (see Vue Events below) instead of onXxx props. Standard HTML attributes (class, style, id, etc.) are forwarded to the root div via the default inheritAttrs behavior.

Prop	Type	Description
theme	string	Name of a built-in or custom theme (see Themes). Applied as a theme-<name> class on the root element.

Vue Events

Event	Payload	Description
data	(data: string)	Emitted when the terminal produces data (user input or host response). When no listener is attached, input is echoed back automatically.
title	(title: string)	Emitted when the terminal title changes via an escape sequence.
resize	(cols: number, rows: number)	Emitted after the terminal is resized.
ready	(wt: WTerm)	Emitted once after WTerm.init() resolves, carrying the underlying WTerm instance.
error	(err: unknown)	Emitted if WASM loading or initialization fails.

WTerm Methods

Instance methods on the vanilla WTerm class:

WTerm renders synchronized output blocks (CSI ?2026) atomically when the mode closes. Each block can hold rendering for at most one second from its opening sequence. Ordinary payload does not extend that deadline. If the deadline expires, WTerm resumes painting until a fresh block begins.

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;
}

Template Ref (Vue)

The Vue <Terminal> component exposes the same methods directly on its instance — no separate composable. Access them via useTemplateRef:

<script setup lang="ts">
import { useTemplateRef } from "vue";
import { Terminal } from "@wterm/vue";

const term = useTemplateRef("term");
</script>

<template>
  <Terminal ref="term" />
</template>

Member	Type	Description
write	(data: string | Uint8Array) => void	Write data to the terminal. Safe to call after the ready event; calls before mount are ignored.
resize	(cols: number, rows: number) => void	Resize the terminal grid. Calls before mount are ignored.
focus	() => void	Focus the terminal input.
instance	WTerm | null	Underlying WTerm instance. null until the component has mounted; the WASM bridge is only available after the ready event.

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, afterChunk?)	Write a UTF-8 string and optionally run a callback after each internal chunk
writeRaw(data, afterChunk?)	Write raw bytes and optionally run a callback after each 8192-byte internal chunk
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	Dequeue one pending host response (e.g. DSR), or null.
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
synchronizedOutput(): boolean	Whether synchronized output mode (2026) 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.)
  width?: number; // 1 = narrow, 2 = wide leading cell, 0 = continuation
}

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