vue-termui

Vue TermUI is a custom Vue 3 renderer that allows you to build Terminal User Interfaces (TUIs) using standard Vue patterns. Instead of rendering to the DOM, components render to the terminal using real flexbox layouts, styled text, and support for keyboard/mouse input and focus management.

If you are familiar with Vue, you can use the Composition API, refs, computeds, slots, and directives like v-if, v-for, and v-model to build interactive terminal applications.

<script setup lang="ts">
import { Box, Text, useInterval, ref } from 'vue-termui'

const count = ref(0)
useInterval(() => count.value++, 1000)
</script>

<template>
  <Box border borderStyle="rounded" :padding="1">
    <Text bold fg="#42b883">Uptime: {{ count }}s</Text>
  </Box>
</template>

Use @vue-termui/three to render Three.js WebGPU scenes directly inside a vue-termui terminal application. This package is a port of @opentui/three designed to run on Node.js (version 26.3.0 or higher) using the --experimental-ffi flag.

<script setup lang="ts">
import { shallowRef } from 'vue-termui'
import { Three, onFrame } from '@vue-termui/three'
import { Scene, PerspectiveCamera } from 'three'

const scene = new Scene()
const camera = new PerspectiveCamera(45, 1, 0.1, 100)
// build your scene...
</script>

<template>
  <Three :scene="scene" :camera="camera" />
</template>

The <Box> component is the fundamental layout building block in Vue TermUI, acting as the terminal equivalent of a <div>. It is a flexbox container, meaning layout, borders, padding, margins, and background are handled natively using props that mirror CSS flexbox properties. By default, boxes lay their children out in a row.

<script setup lang="ts">
import { Box, Text } from 'vue-termui'
</script>

<template>
  <Box flexDirection="column" :gap="1" border borderStyle="rounded" :padding="1">
    <Text>First row</Text>
    <Text>Second row</Text>
  </Box>
</template>

In the legacy terminal input model, many key combinations are encoded using the same byte sequences, making them indistinguishable to your application. Avoid relying on these combinations for distinct actions:

Note on Modifiers: The platform 'command' modifier (Cmd / Super / Win) has no encoding in the legacy model. Cmd+Enter will not reach your app via legacy input.

Choose between <Newline> and <Box> based on your layout needs:

1. Use <Box> with gap for spacing between rows in a structured column layout. This is generally cleaner for layout management.

   <Box flexDirection="column" :gap="1">
     <Text>first</Text>
     <Text>second</Text>
   </Box>

2. Use <Newline> when you need a break within a flow of text, such as separating paragraphs inside a single block or adding vertical space between inline <Text> runs.

When designing keybindings for a TUI, you must account for the fact that an input event passes through several layers before reaching your application. Any layer can consume (swallow) the keypress before it reaches your handlers.

The stack consists of:

1. OS / Window Manager: Handles global shortcuts (e.g., fullscreen, window management).
2. Terminal Emulator: Handles menu shortcuts, selection, and mouse protocols.
3. Multiplexer (e.g., tmux/screen): Handles prefix keys, copy-mode, and specific keytables.
4. Your App: Only receives the key events that survived the previous layers.

Practical consequence: Do not build core functionality on key combinations that are likely to be claimed by the OS, terminal, or multiplexer (like Cmd modifiers on macOS or Ctrl+b in tmux).

Vue TermUI functions as a Vue custom renderer built on top of OpenTUI, a high-performance native terminal renderer.

Core Mechanics:

• Component Mapping: Vue components map to OpenTUI renderables. For example, <Box> maps to a flexbox container and <Text> maps to styled text.
• Native Heavy Lifting: OpenTUI manages layout (via real flexbox), drawing, the alternate screen buffer, and input handling.
• Reactivity & Diffing: Because it is a genuine custom renderer rather than simple string concatenation, updates are diffed and patched just like in a web browser. Only the parts of the terminal that changed are redrawn, ensuring high performance.

TIP

This version is a ground-up rewrite on top of OpenTUI. If you are migrating from an earlier version that used TuiBox or onKeyData, note that the API has changed.

To place elements at specific coordinates regardless of other components in the flow, use the position="absolute" prop on a Box.

Note on precision: The renderer does not automatically round coordinates. For smooth motion, it is recommended to maintain position state as floating-point numbers (e.g., in a reactive object) and only use Math.round() when binding those values to the :left and :top props.

Because vue-termui renders through the OpenTUI native engine, it requires Foreign Function Interface (FFI) support. You have two primary options for your runtime:

1. Node.js: Use Node ≥ 26.3 and run your application with the --experimental-ffi flag. You can use --disable-warning=ExperimentalWarning to suppress experimental warnings.
2. Bun: Use Bun, which supports FFI natively without additional flags.

To prevent the terminal process from exiting immediately, use await app.waitUntilExit(). This promise resolves when the application terminates via Ctrl+C, a process signal (like SIGTERM), or a programmatic call to app.exit() or useExit().

Exiting the application automatically restores the terminal (cursor, screen buffer, and raw mode) to ensure the user is left with a clean prompt.

Exit Triggers:

const app = await createApp(App)
app.mount()

// Wait for user to quit before running cleanup
await app.waitUntilExit()
console.log('Goodbye!')