Documentation Index
Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt
Use this file to discover all available pages before exploring further.
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 interface (use ProcessTerminal for stdio)
render(component: Component) - Render a componentshowOverlay(component: Component, options?: OverlayOptions) - Show an overlayhideOverlay(handle: OverlayHandle) - Hide an overlayfocus(component: Component) - Focus a componentaddInputListener(listener: (data: string) => { consume?: boolean }) - Add input listenerclose() - Clean up and restore terminal
Container
Container for multiple components with vertical layout.
const container = new Container();
container.addChild(component1);
container.addChild(component2);
addChild(component: Component) - Add a child componentremoveChild(component: Component) - Remove a child componentclear() - 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);
border
'single' | 'double' | 'rounded' | 'none'
Border style. Default: 'single'
Border color (e.g., 'blue', '#ff0000')
Padding (top, right, bottom, left)
Title displayed at top of border
Text
Simple text component.
const text = new Text("Hello, world!");
text.setText("New text");
setText(text: string) - Update text contentgetText() - Get current text
TruncatedText
Text with automatic truncation.
const text = new TruncatedText("Very long text...", {
maxLines: 10,
ellipsis: true,
});
Show ellipsis when truncated. Default: true
Spacer
Vertical spacing component.
const spacer = new Spacer(2); // 2 blank lines
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();
Language for syntax highlighting (e.g., 'typescript', 'markdown')
setText(text: string) - Set editor contentgetText() - Get editor contentclear() - Clear editorfocus() - Focus the editoron(event: string, handler: Function) - Subscribe to events
Events:
submit - User pressed Enter/Ctrl+Entercancel - User pressed Escapechange - 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}`);
});
Enable fuzzy search. Default: false
setItems(items: SelectItem[]) - Update itemsgetSelectedItem() - Get selected itemon(event: string, handler: Function) - Subscribe to events
Events:
select - Item selectedcancel - 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,
});
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,
});
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,
});
Base64 encoded image data
MIME type (e.g., 'image/png')
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);
});
};