Docs/Standard library

term/tui

Build terminal applications with a Model interface, asynchronous commands, keyboard events, and terminal rendering.

Model, messages, and commands#

Import term/tui. Applications implement the Model interface with Init, Update, and View methods. Init returns the first command; Update handles a message and returns the next model and command; View returns the display. All three run serially on the thread calling Run. Value models return updated copies; pointer models mutate state and return their pointer. Interface dispatch invokes the concrete implementation.

Msg is an alias for any, so application-defined values can be messages. Cmd is an alias for func() Msg. Commands execute on native workers and return messages to the application loop. Keep model mutation in Update; capture immutable inputs for commands. Return tui.NoCmd or a zero Cmd when no effect is needed.

Ocean
interface Model {
    Init() Cmd;
    Update(message Msg) (Model, Cmd);
    View() string;
}
type Msg = any;
type Cmd = func() Msg;

A counter with asynchronous ticks#

Each tick command waits on a worker and returns a message; Update schedules the next tick. The application thread remains available for keyboard and resize events. Ctrl+C is a key message in raw mode, so handle it explicitly.

Ocean
package main;

import "term/tui";
import "io";
import "time";

struct counter { count int; }
struct tickMsg {}
func (model counter) Init() tui.Cmd { return tui.Tick(time.Second, tickMsg{}); }
func (model counter) Update(message tui.Msg) (tui.Model, tui.Cmd) {
    switch (event := message.(type)) {
        case tui.KeyMsg:
            if (event.Key == "ctrl+c" || event.Text == "q") return model, tui.Quit;
            if (event.Key == "up" || event.Text == "+") model.count++;
            if (event.Key == "down" || event.Text == "-") model.count--;
        case tickMsg:
            model.count++;
            return model, tui.Tick(time.Second, tickMsg{});
        case tui.EOFMsg: return model, tui.Quit;
    }
    return model, tui.NoCmd;
}
func (model counter) View() string {
    return "Count: " + io.Sprint(model.count) + "\n↑/↓ or +/- to change · q to quit";
}
func main() {
    program := tui.NewProgram(counter{}, tui.Options{AltScreen: true});
    program.Run().unwrap();
}

Program lifecycle#

NewProgram accepts zero or one Options value. Options{} uses stdin/stdout, raw input, and redraws from the current line. AltScreen: true uses the alternate screen. Headless: true overrides terminal options, disables input, size events, View calls, and rendering. It supports command-only applications and tests without a terminal.

Keep Program at a stable address and never copy it after first use: it contains a mutex. Run is single-use. Send and Quit are safe from other threads; keep Program alive until those callers finish. The queue is unbounded. FIFO order is enqueue order; concurrent commands may complete in any order, and pending messages can be discarded when Quit is processed.

Program lifecycle reference
APIBehavior
NewProgram(model Model, options ...Options) ProgramConstruct a single-use application.
(*Program).Run() Result<Model>Return the final model, or a terminal/I/O/command-panic error.
(*Program).Send(message Msg) boolQueue before or during Run; false after shutdown.
(*Program).Quit() boolEnqueue QuitMsg.

Effects, composition, and I/O#

Return command function values from Init or Update; the runner invokes them on workers. Batch runs children concurrently and delivers results as they finish. Sequence executes commands in order and waits for nested batches to finish; it enqueues results without waiting for Update to process them. Empty composites are valid.

Tick is a one-shot approximate timer in nanoseconds (for example, time.Second); negative durations panic. Schedule another tick from Update to repeat. The event loop polls approximately every 5ms; Tick uses time.Sleep. Each effect uses a native thread; bound the amount of concurrent work.

Read and Write operate on preopened independent streams. Do not use them on the terminal’s stdin/stdout. Open streams before Run, close them afterward, and use one reader/writer per stream. The existing os file registry is not internally synchronized: concurrent opening/closing/registering files while the terminal loop accesses that registry is unsupported. Custom commands may return application-specific I/O messages. Errors from Read/Write become ErrorMsg, rather than automatically stopping Run.

Effects, composition, and I/O reference
APIBehavior
NoCmd / zero(tui.Cmd)No effect.
QuitCommand returning QuitMsg.
Batch(commands ...Cmd) CmdConcurrent effects.
Sequence(commands ...Cmd) CmdOrdered effects, including nested batches.
Tick(nanoseconds int, message Msg) CmdOne-shot timer.
Read(file os.File, count int) CmdRead up to count bytes; count must be positive. Returns ReadMsg or ErrorMsg.
Write(file os.File, text string) CmdWrite all text. Returns WriteMsg or ErrorMsg.

Messages and keyboard input#

KeyMsg.Text contains one printable UTF-8 scalar; Key is rune, or space for ASCII space. Other key names include enter, tab, backspace, esc, up, down, left, right, home, end, insert, delete, pgup, pgdown, shift+tab, f1–f12, and ctrl+a–ctrl+z, with enter/tab/backspace taking precedence. NUL is ctrl+space; remaining control bytes use numeric names such as ctrl+28. Alt prefixes set Alt.

Split UTF-8 and common CSI/SS3 sequences are buffered. A lone Escape waits about 30ms. Invalid UTF-8 produces replacement characters; unrecognized escape sequences produce unknown keys. Ctrl+C is delivered to Update. Window dimensions are initially queued before Init results and polled approximately every 100ms. EOFMsg stops input polling; Update decides whether to quit.

Messages and keyboard input reference
APIBehavior
KeyMsgKey string, Text string, Alt bool.
WindowSizeMsgWidth int, Height int in terminal cells.
ReadMsgBytes i8[], End bool. Empty successful reads report End; short nonempty reads do not imply EOF.
WriteMsgBytes int successfully written.
ErrorMsgError string from an I/O command.
EOFMsgTerminal input ended.
QuitMsgStops Run; not delivered to Update.
NoneMsgIgnored; not delivered to Update.

Cancellation and terminal restoration#

Run restores raw settings, shows the cursor, leaves the alternate screen, and restores Windows output mode on normal return, returned errors, and ordinary model-panic unwinding. Model panics propagate; command panics are recovered and become Run errors. OS signal termination, os.Exit, native crashes, and SIGKILL bypass deferred cleanup. Only one program may own the terminal at a time; do not read stdin or write stdout elsewhere during Run.

Shutdown requests cooperative cancellation and joins outstanding commands, including nested batch children. Command defers run. Arbitrary blocking native I/O cannot be forcibly interrupted and may delay Run returning until the call finishes. Terminal restoration occurs before worker joins. Use bounded I/O or application-specific cancellation. External threads and resources remain the caller’s responsibility; do not Return/Kill the Run thread. Pointers in messages still borrow their pointees.

Rendering and platforms#

Views redraw when changed or resized, clear stale content, translate newlines to CRLF, and accept SGR styles/colors. Other control characters are filtered. Excess lines/columns are clipped; the last column is reserved to avoid autowrap. Common combining/East Asian widths are estimated. Full grapheme/emoji layout, mouse input, bracketed paste, focus events, and extended keyboard protocols are not implemented.

The library uses term and native threads on Linux x86-64/AArch64/RISC-V64, macOS x86-64/AArch64, and Windows x86-64/AArch64 with a VT-capable console. Windows VT output mode is enabled and restored. WebAssembly compilation fails because native threading is required. Linux PTY behavior is tested; real Windows/macOS execution still needs host validation. Use a compiler with interface method dispatch and native thread support.