Vue Termui

vue-termui

Build terminal interfaces with Vue 3 and the public vue-termui API. This file covers layout and common components. Load a reference only when the task needs it:

• Markdown or images: specialized components
• Additional implementation patterns: cookbook
• Focus, events, refs, renderer constraints, lifecycle, Vite, or 3D: advanced
• Core component implementation or a new wrapper: component development

Essential rules

• In apps, import components, composables, and Vue APIs from vue-termui. Do not import from vue or @opentui/core.
• Use PascalCase public components. Treat tui-* tags as internal renderer hosts.
• Use Box for layout and Text for text. Do not rely on CSS, HTML, DOM APIs, or browser behavior.
• Keep text nodes inside Text. Its children must resolve directly to strings or text nodes: do not nest components or put conditional <template> fragments inside it. Compute conditional lines as strings, or use styled-text helpers for inline runs.
• Prefer percentage or flex sizing inside bordered containers. Terminal dimensions are measured in cells.
• Give ScrollBox, images, editors, and other content a useful constraint through width, height, or flex props.
• Use the existing component source, co-located spec, and a similar playground page as the current API reference.
• Keep changes focused. Run the narrowest relevant test, then pnpm test:types and pnpm lint.

Choose a component

Import every item from vue-termui. Native layout and rendering options pass through unless the wrapper documents otherwise.

Box

Box is the flexbox layout container. These value types repeat below:

• Dimension: a cell count such as 20, 'auto', or a percentage such as '50%'
• Color: a named/hex string or an OpenTUI RGBA value (ColorInput)
• Gap/padding: a cell count or percentage; margin and position also accept 'auto'

Size and flex

Numeric sizes are terminal cells. Percentage dimensions and flex growth adapt to available space. A fixed width can overflow a parent's interior because borders and padding consume cells; use width="100%" or flexGrow inside framed layouts.

<Box :width="60" :height="12" flexDirection="column" :gap="1" border :padding="1">
  <Box flexDirection="row" alignItems="center" :columnGap="2">
    <Text>Fixed</Text>
    <Box :flexGrow="1"><Text>Uses remaining width</Text></Box>
  </Box>
  <Box :flexGrow="1" justifyContent="center" alignItems="center">
    <Text>Centered in remaining space</Text>
  </Box>
</Box>

Spacing

Position and overflow

Border and fill

<Box
  :border="['top', 'bottom']"
  borderStyle="rounded"
  borderColor="#666"
  focusedBorderColor="#42b883"
  title=" Results "
  titleAlignment="center"
  backgroundColor="#111"
  :paddingX="2"
>
  <Text>Content</Text>
</Box>

Visibility, focus, and identity

Input handlers

All handlers receive the native event. Keyboard and paste handlers only run while the box is focused, so also set focusable.

Low-level rendering

These native OpenTUI props are only relevant to custom rendering or animation:

Put layout siblings in a Box. Give ScrollBox a width, height, or flex constraint so it has a viewport. Its scrollX and scrollY options are constructor-only; change a :key to remount when they must change.

Text

Put every visible string and interpolation inside Text. Text accepts slot content plus fg, bg, wrap, bold, dim, italic, underline, strikethrough, inverse, and blink.

Do not nest Text. For inline colors or attributes, pass content built with t, fg, bg, bold, italic, and the other styled-text helpers exported by vue-termui.

Text defaults to flexShrink: 0. A flex-shrunk wrapped text renderable can paint over following rows, so override this only with a tested layout. Use Newline for one or more explicit line breaks.

Common component contracts

• Input is controlled through v-model. input fires for each edit, change after a committed change, and enter on Return.
• Textarea uses its model as the initial buffer, then owns its cursor, undo history, and content. Changing the model later does not replace the buffer. Change a :key to reset it. Meta or Cmd plus Enter emits submit.
• Select and TabSelect models contain an option index, not its value. Select options require name and can include description and value; it emits select(option, index) on commit. TabSelect options require name and description; it emits changed on movement and selected on commit.
• ProgressBar requires value; max defaults to 1, numeric width to 25, and char to █. Its width is a cell count, not a general layout Dimension, so percentages such as width="100%" are invalid. Derive a responsive number from useTerminalSize. Use color and trackColor for its filled and empty cells.
• Input, Textarea, Select, TabSelect, and ScrollBox are focusable by default. Use autofocus for the initial target and focusable="false" to remove an element from managed navigation. The first mounted autofocus target wins. A focused ScrollBox supports arrows, hjkl, PageUp/PageDown, Home/End, and the mouse wheel.

Basic composition

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

const name = ref('')
</script>

<template>
  <Box flexDirection="column" :gap="1" borderStyle="rounded" :padding="1">
    <Text bold fg="#42b883">Profile</Text>
    <Input v-model="name" width="100%" placeholder="Name" autofocus />
    <Text dim>{{ name || 'Waiting for input' }}</Text>
  </Box>
</template>

Runtime

Creating an OpenTUI renderer requires Node.js 26.3 or newer with --experimental-ffi. Renderer tests use:

NODE_OPTIONS='--experimental-ffi --disable-warning=ExperimentalWarning' pnpm exec vitest run <spec>

The playground dev command already supplies the required flag:

pnpm --filter playground dev

For standalone apps and examples, typechecking and building cannot catch every native render-tree constraint. After those checks, launch the built app briefly under the real renderer, exercise at least one interaction, and quit cleanly:

node --experimental-ffi --disable-warning=ExperimentalWarning dist/main.js