wterm

Svelte

The @wterm/svelte package provides a <Terminal> component for Svelte 5 applications. It re-exports the DOM and core APIs from @wterm/dom so the component and terminal types can come from one import.

Use <Terminal aria-label="Build shell" aria-describedby="shell-help" /> to name and describe the actual input. Label attributes stay synchronized when they change. The wrapper is a group; input is the single editable control. tabindex={-1} removes input from page tab entry. Press Escape, then Tab to move focus out of the terminal, or Escape, then Shift+Tab to move backward. Use readText() on the WTerm instance to present a stable snapshot of retained output in a labelled, read-only text area; see Reading Terminal Output. See Input Accessibility.

Install

npm install @wterm/dom @wterm/svelte svelte

Basic Usage

<script lang="ts">
import { Terminal } from "@wterm/svelte";
import "@wterm/svelte/css";
</script>

<Terminal />

The WASM binary is embedded in the package — no extra setup is required. To serve it separately, pass wasmUrl.

Custom Input Handling

Typed input is echoed back by default. In Svelte 5, pass onData when input should be sent to a PTY or another backend:

<script lang="ts">
import { Terminal } from "@wterm/svelte";
import "@wterm/svelte/css";

function onData(data: string) {
  socket.send(data);
}
</script>

<Terminal {onData} />

onBinary receives raw X10 mouse bytes. Forward its Uint8Array unchanged when the terminal input transport accepts binary data.

The other callback props are onTitle, onBell, onClipboardWrite, onShellIntegration, onWorkingDirectory, onResize, onReady, and onError. onReady receives the underlying WTerm instance.

Props

The component accepts the shared terminal options cols, rows, core, wasmUrl, autoResize, maxImageWidth, maxImageHeight, cursorBlink, announceOutput, renderingPaused, and debug, plus the theme prop. Standard <div> attributes such as class, style, id, and ARIA attributes are forwarded to the root element.

See the Terminal Options and Svelte-only Props reference sections for details.

The Svelte wrapper delegates rendering to @wterm/dom, so a graphics-capable core such as @wterm/ghostty automatically renders direct Kitty PNG/RGB/RGBA images. Set maxImageWidth and/or maxImageHeight to constrain rendered images while preserving their aspect ratio.

Imperative Control

Bind the component instance to call write, resize, and focus:

<script lang="ts">
import { Terminal, type TerminalHandle } from "@wterm/svelte";

let terminal: TerminalHandle;
</script>

<Terminal bind:this={terminal} />

To access the underlying WTerm, bind the instance prop:

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

let instance: WTerm | null = null;
</script>

<Terminal bind:instance />

Themes

Import the stylesheet and pass the theme name:

<script lang="ts">
import { Terminal } from "@wterm/svelte";
import "@wterm/svelte/css";
</script>

<Terminal theme="monokai" />

Built-in themes are solarized-dark, monokai, and light. Define custom themes with CSS custom properties.

The component initializes in onMount, so it is safe to render from an SSR application.

The underlying WTerm instance exposes full-history search, findNext, findPrevious, getSearchState, and clearSearch. Set its onSearchChange callback to keep Find controls current. Use onReady or bind:instance. See Terminal Search for Unicode behavior, progress, and limits.

Selection and Copy

Native Copy preserves terminal line breaks and complete Unicode cells, joining confirmed Ghostty soft wraps. Call getSelectionText() on the underlying WTerm instance to read that text without writing the clipboard. See Selection and Copy for whitespace behavior, return values, and native-selection limits.

With Ghostty's current WASM binary, selections also follow output scrolling and resize/reflow while their text remains intact. Overwritten or discarded text, resets, and screen switches clear them. The same reference covers preservation limits and pending-frame behavior.

Use await wt.selectAll() on the WTerm instance to select all retained history and the active screen without mounting extra rows, then read wt.getSelectionText(). Cmd+A or Ctrl+Shift+A invokes the same action from terminal input. wt.clearSelection() cancels it. See Select All for capture limits, shortcuts, and when selection clears.

Double-click words or paths, or triple-click logical lines. The WTerm methods selectWord({ row, col }) and selectLine(row) create the same native selection, including confirmed Ghostty soft wraps and unmounted history. See Words and Logical Lines for coordinates, boundaries, and limits.

Alt/Option-drag selects rectangular columns; Shift+Alt selects inside mouse-reporting applications. Call selectRectangle(start, end) on the WTerm instance with inclusive retained-row/cell corners. Rectangles preserve selected spaces and physical row breaks and clear on output or resize. See Rectangular Selection for copy shortcuts, coordinates, and limits.

Output announcements

Opt in with announceOutput to announce terminal text changes politely while input has focus. The option defaults to false; component prop changes apply without restarting the terminal, and vanilla callers use term.setOutputAnnouncements(enabled). Announcements are batched and stop when focus leaves input. Bursts are bounded to avoid overwhelming the speech queue. See Output announcements for capture limits, pause/resume behavior, and redraw semantics.

Inactive panes

Use renderingPaused for panes that are not visible. Parsing and terminal effects continue, and resuming paints the latest state without restarting. In vanilla code, call term.setRenderingPaused(paused); framework props are reactive. Browser document visibility also pauses painting. See Inactive panes for focus and capture behavior.

Application clipboard writes require an explicit host policy; see Clipboard requests.

Shell integration

With Ghostty, onWorkingDirectory (or onworkingdirectory) receives raw OSC 7 URI reports, including while rendering is paused. An empty string clears the value. Treat the URI as untrusted metadata; see Working directories.

With Ghostty and a shell emitting OSC 133, onShellIntegration receives the latest prompt, input, running, or completion state and the last reported exit code. Delivery continues while painting is paused; markers in one parser chunk coalesce into current state. See Shell integration for the contract, shell setup, and workspace indicators.

Use the underlying WTerm instance’s scrollToPrompt(-1) and scrollToPrompt(1) methods to navigate previous and next prompts in retained history. See Shell integration for viewport behavior, unsupported cores, and inactive states.

PreviousVueNextVanilla JS