TUI Components

Terminal UI components for building interactive interfaces

The @mariozechner/pi-tui package provides components for building terminal user interfaces.

Import

import {
  TUI,
  Container,
  Box,
  Text,
  Editor,
  SelectList,
  Markdown,
  Loader,
} from "@mariozechner/pi-tui";

Core Components

TUI

The main TUI manager that handles rendering and input.

const tui = new TUI(terminal);

terminal · Terminal · required

Terminal interface (use ProcessTerminal for stdio)

Methods:

• render(component: Component) - Render a component
• showOverlay(component: Component, options?: OverlayOptions) - Show an overlay
• hideOverlay(handle: OverlayHandle) - Hide an overlay
• focus(component: Component) - Focus a component
• addInputListener(listener: (data: string) => { consume?: boolean }) - Add input listener
• close() - Clean up and restore terminal

Container

Container for multiple components with vertical layout.

const container = new Container();
container.addChild(component1);
container.addChild(component2);

Methods:

• addChild(component: Component) - Add a child component
• removeChild(component: Component) - Remove a child component
• clear() - Remove all children

Box

Box container with borders and padding.

const box = new Box({
  border: "rounded",
  borderColor: "blue",
  padding: { top: 1, right: 2, bottom: 1, left: 2 },
  title: "Settings",
});
box.addChild(content);

options · BoxOptions

Show properties

border · 'single' | 'double' | 'rounded' | 'none'

Border style. Default: 'single'

borderColor · string

Border color (e.g., 'blue', '#ff0000')

padding · Padding

Padding (top, right, bottom, left)

title · string

Title displayed at top of border

Text

Simple text component.

const text = new Text("Hello, world!");
text.setText("New text");

Methods:

• setText(text: string) - Update text content
• getText() - Get current text

TruncatedText

Text with automatic truncation.

const text = new TruncatedText("Very long text...", {
  maxLines: 10,
  ellipsis: true,
});

options · TruncatedTextOptions

Show properties

maxLines · number

Maximum lines to display

ellipsis · boolean

Show ellipsis when truncated. Default: true

Spacer

Vertical spacing component.

const spacer = new Spacer(2); // 2 blank lines

Input Components

Editor

Multi-line text editor with syntax highlighting.

const editor = new Editor({
  placeholder: "Type your message...",
  language: "markdown",
  theme: editorTheme,
  keybindings: DEFAULT_EDITOR_KEYBINDINGS,
});

editor.setText("Initial text");
const content = editor.getText();

options · EditorOptions

Show properties

placeholder · string

Placeholder text

language · string

Language for syntax highlighting (e.g., 'typescript', 'markdown')

theme · EditorTheme

Color theme

keybindings · EditorKeybindingsConfig

Keyboard shortcuts

autocomplete · AutocompleteProvider

Autocomplete provider

Methods:

• setText(text: string) - Set editor content
• getText() - Get editor content
• clear() - Clear editor
• focus() - Focus the editor
• on(event: string, handler: Function) - Subscribe to events

Events:

• submit - User pressed Enter/Ctrl+Enter
• cancel - User pressed Escape
• change - Text changed

SelectList

Selectable list with keyboard navigation.

const list = new SelectList({
  items: [
    { id: "1", label: "Option 1" },
    { id: "2", label: "Option 2" },
  ],
  theme: selectListTheme,
});

list.on("select", (item) => {
  console.log(`Selected: ${item.id}`);
});

options · SelectListOptions

Show properties

items · SelectItem[] · required

List items

theme · SelectListTheme

Color theme

searchable · boolean

Enable fuzzy search. Default: false

Methods:

• setItems(items: SelectItem[]) - Update items
• getSelectedItem() - Get selected item
• on(event: string, handler: Function) - Subscribe to events

Events:

• select - Item selected
• cancel - User pressed Escape

SettingsList

Settings list with keyboard navigation.

const settings = new SettingsList({
  items: [
    { id: "theme", label: "Theme", value: "dark" },
    { id: "font", label: "Font Size", value: "14" },
  ],
  theme: settingsListTheme,
});

Input

Single-line text input.

const input = new Input({
  placeholder: "Enter text...",
});

input.on("submit", (value) => {
  console.log(`Input: ${value}`);
});

Display Components

Markdown

Markdown renderer with syntax highlighting.

const markdown = new Markdown("# Hello\n\nWorld!", {
  theme: markdownTheme,
});

options · MarkdownOptions

Show properties

theme · MarkdownTheme

Color theme

Methods:

• setContent(markdown: string) - Update content

Image

Image display with iTerm2/Kitty protocol support.

const image = new Image({
  data: base64Data,
  mimeType: "image/png",
  maxWidth: 80,
  maxHeight: 24,
});

options · ImageOptions · required

Show properties

data · string · required

Base64 encoded image data

mimeType · string · required

MIME type (e.g., 'image/png')

maxWidth · number

Maximum width in columns

maxHeight · number

Maximum height in rows

Loader

Spinner animation.

const loader = new Loader();
loader.start();
// ...
loader.stop();

CancellableLoader

Loader with cancel button.

const loader = new CancellableLoader("Loading...", "Press Ctrl+C to cancel");
loader.on("cancel", () => {
  console.log("Cancelled");
});

Example: Complete UI

import {
  TUI,
  ProcessTerminal,
  Container,
  Box,
  Text,
  Editor,
  SelectList,
} from "@mariozechner/pi-tui";

const terminal = new ProcessTerminal();
const tui = new TUI(terminal);

// Create layout
const container = new Container();

// Title
const title = new Box({ title: "My App" });
title.addChild(new Text("Welcome!"));
container.addChild(title);

// Editor
const editor = new Editor({
  placeholder: "Type a message...",
});
container.addChild(editor);

// Submit handler
editor.on("submit", () => {
  const text = editor.getText();
  console.log(`Submitted: ${text}`);
  editor.clear();
});

// Render
tui.render(container);
tui.focus(editor);

// Show dialog overlay
const showDialog = () => {
  const list = new SelectList({
    items: [
      { id: "1", label: "Option 1" },
      { id: "2", label: "Option 2" },
    ],
  });
  
  const handle = tui.showOverlay(list, {
    anchor: "center",
    width: 40,
    maxHeight: 10,
  });
  
  list.on("select", (item) => {
    console.log(`Selected: ${item.label}`);
    tui.hideOverlay(handle);
  });
  
  list.on("cancel", () => {
    tui.hideOverlay(handle);
  });
};