---
title: Svelte
url: "https://wterm.dev/svelte"
docs_index: /llms.txt
lastUpdated: 2026-09-28
navTitle: "Svelte"
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

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](/api-reference#reading-terminal-output). See [Input Accessibility](/api-reference#input-accessibility).

## Install

```bash
npm install @wterm/dom @wterm/svelte svelte
```

## Basic Usage

```svelte
<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:

```svelte
<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](/api-reference#terminal-options) and
[Svelte-only Props](/api-reference#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`:

```svelte
<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:

```svelte
<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:

```svelte
<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.

## Terminal Search

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](/api-reference#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](/api-reference#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](/api-reference#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](/api-reference#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](/api-reference#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](/api-reference#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](/configuration#inactive-panes) for focus and capture behavior.

Application clipboard writes require an explicit host policy; see [Clipboard requests](/configuration#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](/configuration#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](/configuration#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](/configuration#shell-integration) for viewport
behavior, unsupported cores, and inactive states.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)