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 & JSX — write terminal interfaces with <template>, TSX, or both
• Flexbox layout — powered by Yoga, the same engine behind React Native
• Dev toolkit (experimental) — HMR in the terminal via the @vue-tui/vite plugin (pnpm dev)
• Input and focus primitives — normalized text, paste, and key facts with managed terminal ownership, plus explicit unique focus handles that compose with input subscriptions
• Small public foundation — renderer-owned facts stay public only when application code cannot derive them safely
• Testing harness — out-of-the-box component-level terminal testing — render, simulate input, assert frames

Quick Start

There are two ways to use vue-tui — scaffold a full project, or drop the runtime into an existing one.

1. Scaffold a project (recommended)

A ready-to-develop setup: Vue SFCs and a terminal HMR dev server via the @vue-tui/vite plugin.

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

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

2. Use the runtime standalone

@vue-tui/runtime is a standalone Vue renderer, independent of the @vue-tui/vite plugin. Author components as SFCs and mount them with createApp, using your own build:

<!-- 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 });

• For Vite development, compile SFCs with unplugin-vue/vite, whose default client output is what the terminal renderer needs; JSX uses the HMR-capable @vitejs/plugin-vue-jsx.
• For a production Node bundle, use unplugin-vue/rolldown with tsdown for SFCs, or unplugin-vue-jsx/rolldown for JSX.
• For hot-reload (HMR) support while developing, add the @vue-tui/vite plugin: plugins: [vueSfc(), vueTui()].

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 rather than to a component allowlist. Vue forwards it through any chain of components whose current effective root is one Box or Text, so ordinary custom single-root components and the first-party Newline, Spacer, Spinner, ScrollBox, and non-empty Table inherit it without dedicated support code. An empty Table with no explicit columns renders no host node or layout space. Fragment and text roots keep Vue's development warning and ineffective behavior, Comment roots are silently ineffective, and Static remains the explicit history-boundary exception.

Static is the only export on that subpath, and it is deliberately absent from the package root.