Spinner and progress

Spinner
Progress

Spinner displays an animated character sequence to indicate background activity. It advances one frame on every TickMessage it receives.

Quick start

import com.williamcallahan.tui4j.compat.bubbles.spinner.*;
import com.williamcallahan.tui4j.compat.lipgloss.Style;
import com.williamcallahan.tui4j.compat.lipgloss.color.Color;
import com.williamcallahan.tui4j.compat.bubbletea.*;

public class App implements Model {

    private Spinner spinner;

    public App() {
        spinner = new Spinner(SpinnerType.DOT)
            .setStyle(Style.newStyle().foreground(Color.color("205")));
    }

    @Override
    public Command init() {
        return spinner.init(); // Starts the tick loop
    }

    @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());
    }

    @Override
    public String view() {
        return "\n\n  " + spinner.view() + " Loading…\n\n  (q to quit)";
    }
}

Tick-based animation

Spinner.init() returns a tick() command that schedules the first TickMessage. When update() receives a TickMessage, it advances the frame counter and schedules the next tick — creating a self-sustaining animation loop that runs at each type’s built-in frame rate.

// The tick loop is started automatically by init()
spinner.init(); // → schedules first TickMessage
// update(TickMessage) → advances frame, schedules next TickMessage

Always forward every message to spinner.update(msg), not only tick messages. Other message types (such as FocusMessage) are handled internally by the component.

Styling

spinner.setStyle(Style.newStyle().foreground(Color.color("63")).bold(true));

The style is applied to every rendered frame.

Changing type at runtime

spinner.setType(SpinnerType.MOON);

Available spinner types

Type	Preview	Frame rate
`LINE`	`\| / - \`	100 ms
`DOT`	`⣾ ⣽ ⣻ ⢿ ⡿ ⣟ ⣯ ⣷`	100 ms
`MINI_DOT`	`⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`	83 ms
`JUMP`	`⢄⢂⢁⡁⡈⡐⡠`	100 ms
`PULSE`	`█▓▒░`	125 ms
`POINTS`	`∙∙∙ ●∙∙ ∙●∙ ∙∙●`	143 ms
`GLOBE`	`🌍🌎🌏`	250 ms
`MOON`	`🌑🌒🌓🌔🌕🌖🌗🌘`	125 ms
`MONKEY`	`🙈🙉🙊`	333 ms
`METER`	`▱▱▱ → ▰▰▰ → ▱▱▱`	143 ms
`HAMBURGER`	`☱☲☴☲`	333 ms
`ELLIPSIS`	`. .. ...`	333 ms

Progress renders a horizontal progress bar that transitions smoothly between percentage values using a spring-physics animation.

Quick start

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

public class App implements Model {

    private Progress progress;

    public App() {
        progress = new Progress()
            .withDefaultGradient()
            .withShowPercentage(true)
            .withWidth(60);
    }

    @Override
    public Command init() {
        // Start at 0 % and schedule a tick to increment
        return progress.setPercent(0.0);
    }

    @Override
    public UpdateResult<App> update(Message msg) {
        if (msg instanceof KeyPressMessage) {
            return UpdateResult.from(this, QuitMessage::new);
        }
        UpdateResult<Progress> result = progress.update(msg);
        progress = result.model();
        return UpdateResult.from(this, result.command());
    }

    @Override
    public String view() {
        return "\n  " + progress.view() + "\n\n  (any key to quit)";
    }
}

Setting the percentage

// Jump to a target — triggers spring animation
Command cmd = progress.setPercent(0.75); // 75%
return UpdateResult.from(this, cmd);

// Increment/decrement by a delta
Command inc = progress.incrPercent(0.10); // +10%
Command dec = progress.decrPercent(0.05); // −5%

// Send a SetPercentMessage through the update loop
// (useful when driven by external events)
progress.update(new SetPercentMessage(0.5));

Always return the command from setPercent() / incrPercent() / decrPercent() through your UpdateResult. The command schedules the next animation FrameMessage; dropping it stops the animation.

Width

progress.withWidth(80);    // Fluent builder
progress.setWidth(80);     // Setter

Percentage display

progress.withShowPercentage(true);          // Default: true
progress.withoutPercentage();               // Disable
progress.withPercentFormat(" %3.0f%%");    // Custom format string
progress.withPercentageStyle(
    Style.newStyle().bold(true)
);

Colors and gradient

progress.withDefaultGradient(); // #5A56E0 → #EE6FF8

progress.withGradient("#FF6B6B", "#4ECDC4");

// Gradient shifts as the bar fills
progress.withScaledGradient("#5A56E0", "#EE6FF8");

progress.withFullColor("#7571F9");
progress.withEmptyColor("#606060");

Characters

progress.withFull('█');   // Character for the filled portion
progress.withEmpty('░');  // Character for the empty portion

Spring physics animation

The spring animation interpolates smoothly between the current displayed percentage and the target. You can tune the physics:

// frequency: oscillation speed (higher = faster convergence)
// damping:   bounce suppression (1.0 = critically damped, no overshoot)
progress.setSpringOptions(30.0, 1.0);

boolean animating = progress.isAnimating(); // True while frames are in flight
double shown = progress.percentShown();     // Currently rendered percentage
double target = progress.targetPercent();   // Target percentage

Static rendering

Call viewAs() to render the bar at an arbitrary percentage without the animation loop:

String bar = progress.viewAs(0.65); // Renders at exactly 65%

Spinner & Progress

You are here.

Other components

FilePicker, Paginator, Stopwatch, Timer, and more.

Get Started

Core Concepts

Components

Guides

Compatibility

Spinner and progress

Quick start

Tick-based animation

Styling

Changing type at runtime

Available spinner types

Quick start

Setting the percentage

Width

Percentage display

Colors and gradient

Characters

Spring physics animation

Static rendering

Spinner & Progress

Other components

​Quick start

​Tick-based animation

​Styling

​Changing type at runtime

​Available spinner types

​Quick start

​Setting the percentage

​Width

​Percentage display

​Colors and gradient

​Characters

​Spring physics animation

​Static rendering

Spinner & Progress

Other components

Quick start

Tick-based animation

Styling

Changing type at runtime

Available spinner types

Quick start

Setting the percentage

Width

Percentage display

Colors and gradient

Characters

Spring physics animation

Static rendering