Spring Boot integration

TUI4J works naturally inside a Spring Boot application. Spring manages the lifecycle of your model beans, JPA repositories feed data into list components, and a CommandLineRunner hands control to the TUI at startup.

Dependencies

Add the Spring Boot BOM and the required starters to your build. The example application uses Gradle with a version catalog:

dependencies {
    // Spring Boot BOM (keeps all Spring versions aligned)
    implementation(platform("org.springframework.boot:spring-boot-dependencies:3.5.10"))

    // TUI4J core
    implementation("com.williamcallahan:tui4j:0.3.2-preview")

    // Spring Data JPA
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")

    // In-memory database for development
    runtimeOnly("com.h2database:h2:2.2.224")

    // Lombok (optional, used in examples)
    compileOnly("org.projectlombok:lombok:1.18.34")
    annotationProcessor("org.projectlombok:lombok:1.18.34")
}

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>3.5.10</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.williamcallahan</groupId>
    <artifactId>tui4j</artifactId>
    <version>0.3.2-preview</version>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
  </dependency>
  <dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
  </dependency>
</dependencies>

Integration walkthrough

Create the Spring Boot application class

The entry point is a standard @SpringBootApplication class. Nothing TUI-specific is needed here.

SpringExampleApplication.java

@SpringBootApplication
public class SpringExampleApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringExampleApplication.class, args);
    }
}

Launch the TUI from a CommandLineRunner

Implement CommandLineRunner as a Spring component. Inject your root model bean and start a Program inside run(). Spring calls this after the application context is fully initialized, so all beans are available.

Tui4jCommandLineRunner.java

@Component
public class Tui4jCommandLineRunner implements CommandLineRunner {

    private final MainViewModel tui4jApplication;

    public Tui4jCommandLineRunner(MainViewModel tui4jApplication) {
        this.tui4jApplication = tui4jApplication;
    }

    @Override
    public void run(String... args) throws Exception {
        new Program(tui4jApplication)
                .withAltScreen()
                .run();
    }
}

withAltScreen() hides the Spring startup logs behind the TUI and restores the terminal to its original state when the program exits.

Define a JPA entity and repository

Use standard Spring Data JPA. The example application stores books with authors:

Book.java

@Entity
@Table(name = "books")
@Data
public class Book {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column
    private String title;

    @Column
    private String synopsis;

    @Column(length = 2048)
    private String description;

    @ManyToMany(cascade = CascadeType.PERSIST, fetch = FetchType.EAGER)
    @JoinTable(
            name = "book_authors",
            joinColumns = @JoinColumn(name = "book_id"),
            inverseJoinColumns = @JoinColumn(name = "author_id")
    )
    private List<Author> authors = new LinkedList<>();
}

BookRepository.java

public interface BookRepository extends JpaRepository<Book, Long> {

    @Query(name = "Book.findByTitleIsContaining")
    Page<Book> findByTitleIsContaining(@Param("title") String title, Pageable pageable);
}

Implement ListDataSource with your JPA repository

ListDataSource is the interface that feeds items into the TUI List component. Inject the JPA repository and implement fetchItems to return a page of results.

BookDataSource.java

@Component
@RequiredArgsConstructor
public class BookDataSource implements ListDataSource {

    private final BookRepository bookRepository;

    @Override
    public FetchedItems fetchItems(int page, int perPage, String filterValue) {
        long allItems = bookRepository.count();
        PageRequest pageRequest = PageRequest.of(page, perPage);

        Page<Book> filteredBooks = bookRepository
                .findByTitleIsContaining(filterValue, pageRequest);

        java.util.List<FilteredItem> items = filteredBooks.stream()
                .map(BookItem::new)
                .map(item -> new FilteredItem(0, item, new int[0]))
                .toList();

        return new FetchedItems(
                items,
                filteredBooks.getTotalElements(),
                allItems,
                filteredBooks.getTotalPages()
        );
    }
}

Wrap your entity in a DefaultItem implementation:

BookItem.java

@RequiredArgsConstructor
public class BookItem implements DefaultItem {

    private final Book book;

    @Override
    public String title() {
        return book.getTitle();
    }

    @Override
    public String description() {
        return book.getSynopsis();
    }

    @Override
    public String filterValue() {
        return book.getTitle();
    }
}

Wire everything together in the root model

The root model is a Spring @Component that receives your BookDataSource and delegate factory by constructor injection. It creates a List component and passes it the data source.

MainViewModel.java

@Component
public class MainViewModel implements Model {

    private static final int LIST_WIDTH = 50;

    private final List list;
    private final BooksGenerator booksGenerator;
    private Spinner spinner;
    private boolean booksGenerated;

    public MainViewModel(BookItemDelegateFactory delegateFactory,
                         BookDataSource bookDataSource,
                         BooksGenerator booksGenerator) {
        this.list = new List(bookDataSource, delegateFactory.newDelegate(), 0, 0);
        this.list.setTitle("Books");
        this.spinner = new Spinner(SpinnerType.DOT);
        this.booksGenerator = booksGenerator;
    }

    @Override
    public Command init() {
        // Run spinner and seed the database in parallel
        return Command.batch(
                spinner.init(),
                this::generateBooks
        );
    }

    private Message generateBooks() {
        booksGenerator.generateBooks(1000);
        return new BooksGenerated();
    }

    @Override
    public UpdateResult<? extends Model> update(Message msg) {
        if (msg instanceof WindowSizeMessage ws) {
            return UpdateResult.from(this, list.setSize(LIST_WIDTH, ws.height()));
        }
        if (msg instanceof BooksGenerated) {
            this.booksGenerated = true;
            return UpdateResult.from(this, list.init());
        }
        if (!booksGenerated) {
            return UpdateResult.from(this, spinner.update(msg).command());
        }
        return UpdateResult.from(this, list.update(msg).command());
    }

    @Override
    public String view() {
        if (!booksGenerated) {
            return spinner.view() + " Generating books";
        }
        return list.view();
    }

    record BooksGenerated() implements Message {}
}

Configure the data source

For development, H2 in-memory mode requires no external database. Add application.yml:

application.yml

spring:
  datasource:
    url: jdbc:h2:mem:spring_example_db
    driverClassName: org.h2.Driver
    username: sa
    password: password
  jpa:
    database-platform: org.hibernate.dialect.H2Dialect

The tui-daemon-combo pattern

Some applications need to run as a background daemon (without a terminal) or as an interactive TUI depending on how they are started. The pattern branches on a CLI flag:

main method

public static void main(String[] args) {
    boolean daemonMode = Arrays.asList(args).contains("--daemon");

    if (daemonMode) {
        runDaemon();   // headless background processing
    } else {
        runTUI();      // interactive terminal UI
    }
}

private static void runTUI() {
    // Suppress logging so it doesn't corrupt the terminal output
    Logger rootLogger = Logger.getLogger("");
    for (java.util.logging.Handler handler : rootLogger.getHandlers()) {
        handler.setLevel(Level.WARNING);
    }
    new Program(new MyModel()).run();
}

private static void runDaemon() {
    System.out.println("Running in daemon mode (headless)...");
    // perform background work in a loop
}

In daemon mode, standard output is fine for logging because no TUI renderer is active. In TUI mode, write logs to a file or redirect them to suppress terminal corruption.

Mouse input

Handle clicks and motion in your TUI

Animations with Harmonica

Spring physics for smooth transitions

Get Started

Core Concepts

Components

Guides

Compatibility

Spring Boot integration

Dependencies

Integration walkthrough

The tui-daemon-combo pattern

Mouse input

Animations with Harmonica

​Dependencies

​Integration walkthrough

​The tui-daemon-combo pattern

Mouse input

Animations with Harmonica

Dependencies

Integration walkthrough

The tui-daemon-combo pattern