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

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

The `@wterm/vue` package provides a `<Terminal>` component for integrating wterm into Vue 3 applications. It re-exports everything from `@wterm/dom`, so a single import covers both the component and its types.

With Ghostty, `@working-directory="onDirectory"` 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).

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/vue
```

## Basic Usage

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

<template>
  <Terminal />
</template>
```

## Custom Input Handling

By default, typed input is echoed back to the terminal. Listen to the `data` event when you need control over input — for example, sending it to a server:

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

const term = useTemplateRef("term");

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

<template>
  <Terminal ref="term" @data="onData" />
</template>
```

## Props

The `<Terminal>` component accepts all [shared terminal options](/api-reference#terminal-options) (`cols`, `rows`, `core`, `wasmUrl`, `autoResize`, `maxImageWidth`, `maxImageHeight`, `cursorBlink`, `announceOutput`, `renderingPaused`) plus [Vue-only props](/api-reference#vue-only-props) (`theme`). Pass a [`TerminalCore`](/ghostty) instance to the `core` prop to use an alternative emulation backend.

Because `inheritAttrs` is enabled, standard DOM attributes (`class`, `style`, `id`, ARIA props, etc.) are forwarded to the root `<div>`.

The Vue 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 their rendered
size in CSS pixels; images preserve their aspect ratio and are never enlarged.
Image canvases are decorative (`aria-hidden`, non-focusable, and
pointer-transparent); text remains the accessible terminal surface.

The underlying DOM terminal also answers Kitty pixel geometry queries from the
rendered viewport, so direct image clients can negotiate their display size.

## Events

Input callbacks are exposed as Vue events rather than `onXxx` props:

```vue
<Terminal
  @data="onData"
  @title="onTitle"
  @bell="onBell"
  @clipboard-write="onClipboardWrite"
  @resize="onResize"
  @ready="onReady"
  @error="onError"
/>
```

See the full [Vue Events](/api-reference#vue-events) reference for payload types.

The `binary` event carries raw X10 mouse bytes as a `Uint8Array`. Forward it
unchanged when the terminal input transport accepts binary data.

## Template Ref

Access imperative methods via a template ref:

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

const term = useTemplateRef("term");

function onReady(wt: WTerm) {
  wt.write("hello\r\n");
  term.value?.resize(120, 40);
}
</script>

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

The exposed methods are `write`, `resize`, `focus`, and `instance` (the underlying `WTerm`, or `null` before mount). See the full [Template Ref](/api-reference#template-ref-vue) reference.

## Themes

Import the stylesheet and switch themes via the `theme` prop:

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

<template>
  <Terminal theme="monokai" />
</template>
```

Built-in themes: `solarized-dark`, `monokai`, `light`. Define custom themes with CSS custom properties (`--term-fg`, `--term-bg`, `--term-color-0` through `--term-color-15`). See [Themes](/themes) for details.

## Nuxt

The component mounts in `onMounted`, so it is SSR-safe out of the box. If you need to guarantee client-only rendering (e.g. for debugging or to skip hydration entirely), wrap it in `<ClientOnly>`:

```vue
<template>
  <ClientOnly>
    <Terminal />
  </ClientOnly>
</template>
```

## 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 the `ready` event or template ref’s `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 and a shell emitting OSC 133, `@shell-integration` 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)