The Elm Architecture

TUI4J is built around The Elm Architecture (TEA), a pattern originating from the Elm programming language and adopted by Go’s Bubble Tea library. Every TUI4J application is a Model — a single object that holds all application state — combined with three pure functions: init, update, and view.

How it works

Init runs once at startup, returning an optional Command to kick off I/O or timers.
The main loop feeds Message values (key presses, timer ticks, window resize events, etc.) into update.
Update returns the next model state plus an optional Command for any side effects.
The main loop calls view on the updated model and redraws the terminal.

This cycle continues until the model returns a QuitMessage command.

The three methods

`init()`

Called exactly once when the program starts. Return a Command to schedule the first piece of async work, or null (or Command.none()) if no startup I/O is needed.

@Override
public Command init() {
    // No startup I/O — return null to skip.
    return null;
}

`update(Message msg)`

Receives every event — key presses, timer ticks, window size changes, custom messages — and returns an UpdateResult pairing the next model state with an optional follow-up Command.

@Override
public UpdateResult<? extends Model> update(Message msg) {
    if (msg instanceof KeyPressMessage kp) {
        return switch (kp.key()) {
            case "q", "Q" -> UpdateResult.from(this, QuitMessage::new);
            default       -> UpdateResult.from(this);
        };
    }
    return UpdateResult.from(this);
}

UpdateResult.from(model) is shorthand for UpdateResult.from(model, null). Both forms are equivalent — a null command is treated as a no-op.

`view()`

Converts the current model state into a plain String. TUI4J computes a diff against the previous frame and redraws only what changed.

@Override
public String view() {
    return String.format("Counter: %d\n\nPress q to quit.", count);
}

view() must be a pure function — no side effects, no I/O. Everything that mutates state belongs in update.

Minimal complete example

The example below implements a simple counter. Press + to increment, - to decrement, and q to quit.

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

public class Counter implements Model {

    private final int count;

    public Counter(int count) {
        this.count = count;
    }

    @Override
    public Command init() {
        return null; // no startup commands
    }

    @Override
    public UpdateResult<? extends Model> update(Message msg) {
        if (msg instanceof KeyPressMessage kp) {
            return switch (kp.key()) {
                case "+" -> UpdateResult.from(new Counter(count + 1));
                case "-" -> UpdateResult.from(new Counter(count - 1));
                case "q" -> UpdateResult.from(this, QuitMessage::new);
                default  -> UpdateResult.from(this);
            };
        }
        return UpdateResult.from(this);
    }

    @Override
    public String view() {
        return String.format("Count: %d\n\n(+/-) change  (q) quit", count);
    }

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

How commands flow back into the loop

A Command is a @FunctionalInterface (specifically () -> Message). When update returns one, the runtime executes it on a background thread, then delivers the resulting Message back into the main loop — which calls update again. This means all side effects (HTTP calls, file I/O, timers) happen outside of update, keeping the update logic synchronous and testable.

Comparison with Bubble Tea (Go)

TUI4J is a direct port of Bubble Tea. The core concepts are identical; only the syntax differs.

public class MyModel implements Model {

    @Override
    public Command init() {
        return null;
    }

    @Override
    public UpdateResult<? extends Model> update(Message msg) {
        if (msg instanceof KeyPressMessage kp && kp.key().equals("q")) {
            return UpdateResult.from(this, QuitMessage::new);
        }
        return UpdateResult.from(this);
    }

    @Override
    public String view() {
        return "Hello, world!\n";
    }
}

type model struct{}

func (m model) Init() tea.Cmd {
    return nil
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        if msg.String() == "q" {
            return m, tea.Quit
        }
    }
    return m, nil
}

func (m model) View() string {
    return "Hello, world!\n"
}

Key differences:

Concept	Bubble Tea (Go)	TUI4J (Java)
Model contract	`tea.Model` interface	`Model` interface
Update return	`(tea.Model, tea.Cmd)`	`UpdateResult<? extends Model>`
Quit	`tea.Quit` command	`QuitMessage::new` command
No command	`nil`	`null` or `Command.none()`

Program

How to instantiate and run a TUI4J program.

Messages and commands

All built-in messages and how to create custom ones.

Get Started

Core Concepts

Components

Guides

Compatibility

The Elm Architecture

How it works

The three methods

`init()`

`update(Message msg)`

`view()`

Minimal complete example

How commands flow back into the loop

Comparison with Bubble Tea (Go)

Program

Messages and commands

​How it works

​The three methods

​init()

​update(Message msg)

​view()

​Minimal complete example

​How commands flow back into the loop

​Comparison with Bubble Tea (Go)

Program

Messages and commands

How it works

The three methods

`init()`

`update(Message msg)`

`view()`

Minimal complete example

How commands flow back into the loop

Comparison with Bubble Tea (Go)