Configuration

Options

The React and Vue Terminal components and the vanilla WTerm constructor accept the same core options — cols, rows, core, wasmUrl, autoResize, cursorBlink, and debug — plus event callbacks onData, onTitle, and onResize (exposed as @data, @title, @resize events in Vue).

See the full API Reference for types, defaults, and descriptions.

Pluggable cores

By default, wterm uses its built-in lightweight Zig WASM core (~12 KB). To use a different terminal emulation backend, pass a TerminalCore instance via the core option. See the Ghostty Core page for an example using libghostty.

React-only

The React Terminal component adds theme, onReady, and onError on top of the shared options. It also spreads standard HTML attributes onto the root div, so you can pass className, style, ARIA attributes, and other DOM props directly.

See React-Only Props for details.

Vue-only

The Vue Terminal component adds a theme prop. onReady and onError are exposed as @ready and @error events instead of props. Standard DOM attributes (class, style, id, ARIA props, etc.) are forwarded to the root <div> via the default inheritAttrs behavior.

See Vue-Only Props and Vue Events for details.

Imperative Handle (React)

When using useTerminal, the returned ref exposes an imperative handle:

import { Terminal, useTerminal } from "@wterm/react";

function App() {
  const { ref } = useTerminal();

  return (
    <Terminal
      ref={ref}
      onReady={(wt) => {
        wt.resize(120, 40);
      }}
    />
  );
}

See the full Imperative Handle reference for all returned methods.

Template Ref (Vue)

Access imperative methods on the Vue component via a template ref:

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

const term = useTemplateRef("term");

function onReady(wt: WTerm) {
  wt.resize(120, 40);
}
</script>

<template>
  <Terminal ref="term" @ready="onReady" />
</template>

See the full Template Ref (Vue) reference for all exposed methods.

WebSocket Transport

For connecting to a remote shell over WebSocket, use the built-in WebSocketTransport:

import { WTerm, WebSocketTransport } from "@wterm/dom";

const ws = new WebSocketTransport({
  url: "wss://your-server.example/shell",
  reconnect: true,
  maxReconnectDelay: 5000,
  onData(data) {
    term.write(data);
  },
  onOpen() {
    console.log("connected");
  },
  onClose() {
    console.log("disconnected");
  },
});

const term = new WTerm(document.getElementById("terminal"), {
  onData(data) {
    ws.send(data);
  },
});

await term.init();
ws.connect();

See the full WebSocketTransport reference for all options, methods, and properties.

The transport buffers any send() calls made before the connection is open and flushes them automatically on connect.