vue-tui

Public beta — the @vue-tui/runtime API is stabilizing toward 1.0; dev-mode HMR is still experimental. Bug reports welcome.

vue-tui is a Vue-native application framework for interactive terminal UIs. Build with components, develop with HMR, test with confidence.

• Vue SFC and JSX: Write terminal interfaces with <template>, TSX, or both.
• Flexbox layout: Yoga provides the same layout engine that React Native uses.
• Development tools: @vue-tui/vite provides hot module replacement (HMR) in the terminal.
• Input and focus: Vue composables handle text, paste, and key events, plus focus state.
• Testing: Use @vue-tui/testing to render components, send terminal input, and inspect frames.

Quick Start

Choose the method that matches your application.

1. Create a standalone TUI application (recommended)

Use this scaffold for a standalone TUI application that controls the Node process and terminal. The Vite config defines the application entry. During development, @vue-tui/vite starts this entry and provides HMR. During a production build, it configures Vite to create one Node file. The Vue compiler creates client render functions in both modes.

pnpm dlx tiged vuejs-ai/vue-tui/templates/vite my-app
cd my-app
pnpm install
pnpm dev        # in-process terminal dev server with HMR
pnpm build      # Vite builds dist/main.mjs
pnpm build:exe  # Vite builds first, then tsdown creates build/main (requires Node.js 26 or later)
pnpm preview    # build, then run the production bundle

Edit src/app.vue and watch the terminal update instantly.

Building an executable requires Node.js 26 or later. On Windows, the executable is build/main.exe.

2. Embed the runtime

Use the runtime directly when vue-tui is part of an existing Node application. The host application uses its existing compiler, build, entry, and process lifecycle without @vue-tui/vite. For an embedded Vite application, use @vitejs/plugin-vue to compile SFCs or @vitejs/plugin-vue-jsx to compile JSX and TSX.

<!-- app.vue -->
<script setup lang="ts">
import { shallowRef } from "vue";
import { Box, Text, useInput } from "@vue-tui/runtime";

const count = shallowRef(0);

useInput((event) => {
  if (event.type === "key") {
    if (event.key.name === "up") {
      count.value++;
    } else if (event.key.name === "down") {
      count.value--;
    }
  }
});
</script>

<template>
  <Box>
    <Text>Count: </Text>
    <Text bold color="green">{{ count }}</Text>
    <Text dimColor> (↑/↓ to change)</Text>
  </Box>
</template>

// main.ts
import { createApp } from "@vue-tui/runtime";
import App from "./app.vue";

createApp(App).mount({ exitOnCtrlC: true });

Table of Contents

• Quick Start
• Packages
• Examples
• @vue-tui/runtime
• @vue-tui/use
• @vue-tui/components
• @vue-tui/testing
• Development
• Contributing
• Credits
• License

Packages

Examples

@vue-tui/runtime

The core renderer: the terminal primitives and the composables that read renderer-owned facts. Package guide.

Components

Box and Text have closed prop surfaces: unknown props, misspellings, browser attributes, and listeners such as @click are rejected at runtime instead of silently ignored. The full prop tables are in the Runtime guide.

v-show belongs to the visual host layer, not to a component allowlist. Vue forwards v-show through a component chain when its current effective root is one Box or Text. Custom single-root components therefore support it without additional code. Newline, Spacer, Spinner, ScrollBox, and a non-empty Table also support v-show. An empty Table with no explicit columns renders no host node or layout space.

Fragment and text roots produce a Vue development warning, and v-show has no effect. Comment roots ignore v-show without a warning. Static remains the explicit history-boundary exception.

Static is the only export on that subpath, and it is deliberately absent from the package root. It has no collection API — use ordinary Vue iteration with stable keys. Each instance commits its output once and then releases its subtree; effective Fullscreen rejects Static.

<script setup lang="ts">
import { Static } from "@vue-tui/runtime/inline";
</script>

<template>
  <Static v-for="entry in completedEntries" :key="entry.id">
    <CompletedEntry :entry="entry" />
  </Static>
</template>

Composables

Each one must be called inside a mounted render tree.

| Composable | Returns | Description | | ------------------------------------------------------