Quickstart

This guide walks through building a small interactive coffee-ordering menu — the canonical TUI4J demo. By the end you will understand the three methods every TUI4J app implements and how to run it with Program. The complete source is in the examples directory.

The Elm Architecture

TUI4J is built on The Elm Architecture. Your application has one Model that owns all state, and three methods that drive the runtime loop:

init() — returns an optional startup command (e.g., start a ticker, make an HTTP request)
update(Message) — receives events (keypresses, timers, responses) and returns the next model state
view() — returns a string that TUI4J renders to the terminal

Build the coffee demo

Define the model

Create a class that implements Model. The model holds your application state — in this case, the cursor position and the selected item.

import com.williamcallahan.tui4j.compat.bubbletea.Command;
import com.williamcallahan.tui4j.compat.bubbletea.Message;
import com.williamcallahan.tui4j.compat.bubbletea.Model;
import com.williamcallahan.tui4j.compat.bubbletea.Program;
import com.williamcallahan.tui4j.compat.bubbletea.UpdateResult;
import com.williamcallahan.tui4j.compat.bubbletea.KeyPressMessage;
import com.williamcallahan.tui4j.compat.bubbletea.QuitMessage;
import com.williamcallahan.tui4j.compat.lipgloss.Style;
import com.williamcallahan.tui4j.compat.lipgloss.color.Color;

public class Demo implements Model {

    private static final Style SELECTION = Style.newStyle().foreground(Color.color("205"));
    private static final String[] CHOICES = {"Espresso", "Americano", "tui4j"};

    private int cursor;
    private String choice;

    public String getChoice() {
        return choice;
    }
}

SELECTION is a Lipgloss style that highlights the active row with a terminal color. CHOICES is the fixed list of menu options.

Implement init()

Return null from init() to indicate there is no startup command. The program starts immediately without waiting for any I/O.

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

Implement update(Message)

update receives every event. Pattern-match on KeyPressMessage to handle keyboard input, then return UpdateResult.from(...) with the next model state and an optional command.

@Override
public UpdateResult<? extends Model> update(Message msg) {
    if (msg instanceof KeyPressMessage keyPressMessage) {
        return switch (keyPressMessage.key()) {
            // "up" and "k" move the cursor up
            case "k", "K", "up" -> UpdateResult.from(this.moveUp());

            // "down" and "j" move the cursor down
            case "j", "J", "down" -> UpdateResult.from(this.moveDown());

            // "enter" selects the current item and quits
            case "enter" -> UpdateResult.from(this.makeChoice(), QuitMessage::new);

            // "q" quits without selecting
            case "q", "Q" -> UpdateResult.from(this, QuitMessage::new);

            default -> UpdateResult.from(this);
        };
    }
    return UpdateResult.from(this);
}

private Model moveUp() {
    if (cursor - 1 < 0) {
        cursor = CHOICES.length - 1;
        return this;
    }
    cursor--;
    return this;
}

private Model moveDown() {
    if (cursor + 1 >= CHOICES.length) {
        cursor = 0;
        return this;
    }
    cursor++;
    return this;
}

private Model makeChoice() {
    for (int index = 0; index < CHOICES.length; index++) {
        if (index == cursor) {
            this.choice = CHOICES[index];
            return this;
        }
    }
    return this;
}

QuitMessage::new is a command supplier that tells TUI4J to exit the program after the current update cycle.

Implement view()

view returns a string. TUI4J re-renders this string to the terminal after every update call, automatically clearing the previous output.

@Override
public String view() {
    StringBuilder buffer = new StringBuilder();
    buffer.append("What kind of Coffee would you like to order?\n\n");

    for (int index = 0; index < CHOICES.length; index++) {
        if (cursor == index) {
            buffer.append(SELECTION.render("[•]", CHOICES[index]));
        } else {
            buffer.append("[ ] ").append(CHOICES[index]);
        }
        buffer.append("\n");
    }
    buffer.append("\n(press q to quit)");
    return buffer.toString();
}

When the cursor is on a row, SELECTION.render(...) applies the Lipgloss style. Other rows are rendered as plain strings.

Run with Program

Create a Program with your model and call run(). After the program exits, you can read state back from the model directly.

public static void main(String[] args) {
    Demo demoModel = new Demo();
    Program program = new Program(demoModel);
    program.run();

    if (demoModel.getChoice() == null) {
        return;
    }
    System.out.printf("\n---\nYou chose: %s!\n", demoModel.getChoice());
}

program.run() blocks until the user quits. Because demoModel is a reference to the same object the runtime uses, its final state is available after run() returns.

Full source

Here is the complete Demo.java file, ready to compile:

import com.williamcallahan.tui4j.compat.bubbletea.Command;
import com.williamcallahan.tui4j.compat.bubbletea.Message;
import com.williamcallahan.tui4j.compat.bubbletea.Model;
import com.williamcallahan.tui4j.compat.bubbletea.Program;
import com.williamcallahan.tui4j.compat.bubbletea.UpdateResult;
import com.williamcallahan.tui4j.compat.bubbletea.KeyPressMessage;
import com.williamcallahan.tui4j.compat.bubbletea.QuitMessage;
import com.williamcallahan.tui4j.compat.lipgloss.Style;
import com.williamcallahan.tui4j.compat.lipgloss.color.Color;

public class Demo implements Model {

    private static final Style SELECTION = Style.newStyle().foreground(Color.color("205"));
    private static final String[] CHOICES = {"Espresso", "Americano", "tui4j"};

    private int cursor;
    private String choice;

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

    @Override
    public UpdateResult<? extends Model> update(Message msg) {
        if (msg instanceof KeyPressMessage keyPressMessage) {
            return switch (keyPressMessage.key()) {
                case "k", "K", "up"   -> UpdateResult.from(this.moveUp());
                case "j", "J", "down" -> UpdateResult.from(this.moveDown());
                case "enter"          -> UpdateResult.from(this.makeChoice(), QuitMessage::new);
                case "q", "Q"         -> UpdateResult.from(this, QuitMessage::new);
                default               -> UpdateResult.from(this);
            };
        }
        return UpdateResult.from(this);
    }

    private Model moveUp() {
        if (cursor - 1 < 0) { cursor = CHOICES.length - 1; return this; }
        cursor--;
        return this;
    }

    private Model moveDown() {
        if (cursor + 1 >= CHOICES.length) { cursor = 0; return this; }
        cursor++;
        return this;
    }

    private Model makeChoice() {
        for (int index = 0; index < CHOICES.length; index++) {
            if (index == cursor) { this.choice = CHOICES[index]; return this; }
        }
        return this;
    }

    @Override
    public String view() {
        StringBuilder buffer = new StringBuilder();
        buffer.append("What kind of Coffee would you like to order?\n\n");
        for (int index = 0; index < CHOICES.length; index++) {
            if (cursor == index) {
                buffer.append(SELECTION.render("[•]", CHOICES[index]));
            } else {
                buffer.append("[ ] ").append(CHOICES[index]);
            }
            buffer.append("\n");
        }
        buffer.append("\n(press q to quit)");
        return buffer.toString();
    }

    public String getChoice() {
        return choice;
    }

    public static void main(String[] args) {
        Demo demoModel = new Demo();
        new Program(demoModel).run();
        if (demoModel.getChoice() != null) {
            System.out.printf("\n---\nYou chose: %s!\n", demoModel.getChoice());
        }
    }
}

Next steps

Components

Explore the full Bubbles library: lists, text inputs, spinners, tables, progress bars, and more.

More examples

Browse the examples directory for spinners, autocomplete, file pickers, tabs, and Spring Boot integration.

Styling with Lipgloss

Learn how to apply colors, borders, padding, and layout joins to your views.

Messages and commands

Understand how to send messages between components and trigger side effects with commands.

Get Started

Core Concepts

Components

Guides

Compatibility

The Elm Architecture

Build the coffee demo

Full source

Next steps

Components

More examples

Styling with Lipgloss

Messages and commands

​The Elm Architecture

​Build the coffee demo

​Full source

​Next steps

Components

More examples

Styling with Lipgloss

Messages and commands

The Elm Architecture

Build the coffee demo

Full source

Next steps