Components overview

TUI4J ships a Java port of the Charm Bubbles library — a collection of ready-made terminal UI components. Each component is self-contained: it owns its state, handles its own key events, and renders its own view. You compose them by embedding them in your application Model.

Available components

List

Filterable, paginated list with static arrays or dynamic data sources.

Text input

Single-line input with placeholder, character limit, and echo modes.

Textarea

Multi-line editor with cursor movement, line numbers, and word operations.

Viewport

Scrollable content area for long text with keyboard and mouse navigation.

Table

Interactive table with column definitions, row data, and keyboard navigation.

Spinner and Progress

Loading spinners and animated progress bars with spring physics.

Other components

FilePicker, Paginator, Stopwatch, Timer, Cursor, and Help.

The Elm Architecture

TUI4J follows the Elm Architecture: every model has three methods.

Method	Role
`init()`	Returns the initial `Command` to run when the program starts.
`update(Message)`	Handles an incoming message and returns the next model state plus an optional command.
`view()`	Renders the current state to a string that is printed to the terminal.

Each Bubbles component is itself a Model. You embed the component as a field in your own Model and delegate update and view calls to it.

Embedding a component

The pattern is the same for every component:

import com.williamcallahan.tui4j.compat.bubbletea.*;
import com.williamcallahan.tui4j.compat.bubbles.spinner.*;

public class App implements Model {

    // 1. Embed the component
    private Spinner spinner = new Spinner(SpinnerType.DOT);

    // 2. Delegate init()
    @Override
    public Command init() {
        return spinner.init();
    }

    // 3. Delegate update(), capture the returned model
    @Override
    public UpdateResult<App> update(Message msg) {
        if (msg instanceof KeyPressMessage kp && "q".equals(kp.key())) {
            return UpdateResult.from(this, QuitMessage::new);
        }

        UpdateResult<? extends Model> result = spinner.update(msg);
        spinner = (Spinner) result.model();
        return UpdateResult.from(this, result.command());
    }

    // 4. Delegate view()
    @Override
    public String view() {
        return "Loading… " + spinner.view();
    }
}

Always reassign the component field from result.model() after calling update(). Components are updated immutably — the returned model may be a new instance.

Starting the program

Pass your root model to Program and call run():

public static void main(String[] args) {
    new Program(new App()).run();
}

Program drives the message loop, renders each frame, and delivers key, mouse, and window-size messages to your model automatically.

Get Started

Core Concepts

Components

Guides

Compatibility

Components overview

Available components

List

Text input

Textarea

Viewport

Table

Spinner and Progress

Other components

The Elm Architecture

Embedding a component

Starting the program

​Available components

List

Text input

Textarea

Viewport

Table

Spinner and Progress

Other components

​The Elm Architecture

​Embedding a component

​Starting the program

Available components

The Elm Architecture

Embedding a component

Starting the program