Skip to content

XTerm Console

A Vaadin Flow add-on that integrates the xterm.js terminal emulator as a server-side Java component.

Overview

Use the XTerm Console add-on to render a fully interactive terminal in the browser and drive it from Java. The XTerm component lets applications write output programmatically, receive user input on the server, and handle ANSI escape sequences. On top of the raw terminal it adds console features such as command-line editing, a configurable prompt, command history, and system-clipboard integration — useful for building admin consoles, REPLs, log viewers, or interactive shells inside a Vaadin app.

Features

  • Send user-entered input text to the server.
  • Write to the console programmatically (write, writeln).
  • Clipboard support with configurable system-clipboard read/write and paste via right/middle click.
  • Command-line editing: cursor keys, home/end, insert mode, delete, backspace.
  • ANSI escape sequence handling.
  • Configurable command prompt and command history.
  • Line events fired on line feed (addLineListener).
  • Text selection API and scrolling controls.
  • Extensive terminal options (font, cursor, theme, scrollback, renderer type, accessibility).
  • Auto-fit to container (fit, setFitOnResize).

Supported versions

Add-on version Vaadin version
3.x 24–25
2.x 23
1.x 14

Refer to the Vaadin Directory page for exact version compatibility.

Installation

From the Vaadin Directory

Available in the Vaadin Directory.

Maven dependency

<dependency>
    <groupId>com.flowingcode.addons</groupId>
    <artifactId>xterm-console</artifactId>
    <version>X.Y.Z</version>
</dependency>

Replace X.Y.Z with the latest released version. Add the Vaadin add-ons repository to your pom.xml:

<repository>
    <id>vaadin-addons</id>
    <url>https://maven.vaadin.com/vaadin-addons</url>
</repository>

For snapshot builds, see maven.flowingcode.com/snapshots.

JavaDoc is published at javadoc.flowingcode.com.

Usage

Create an XTerm, write to it, and react to entered lines:

XTerm xterm = new XTerm();
xterm.writeln("Hello world.\n");
xterm.setCopySelection(true);
xterm.setUseSystemClipboard(UseSystemClipboard.READWRITE);
xterm.addLineListener(ev -> System.out.println(ev.getLine()));
xterm.fit();

Drive a prompt-based console loop:

XTerm xterm = new XTerm();
xterm.setPrompt("$ ");
xterm.writePrompt();
xterm.addLineListener(ev -> {
    xterm.writeln("You typed: " + ev.getLine());
    xterm.writePrompt();
});
xterm.setFitOnResize(true);

Special configuration when using Spring

When running on Spring, allow-list the com.flowingcode package so Vaadin Flow can discover the add-on's components. See Common configuration for details.

API reference

Headline types exposed by the add-on:

  • XTerm — the terminal component you instantiate; extends XTermBase and implements the terminal, console, clipboard, fit, and options interfaces below.
  • ITerminal — core terminal operations: write(String), writeln(String), clear(), reset(), paste(String), focus(), blur(), resize(int, int), plus selection and scrolling methods.
  • ITerminalConsole — console layer: addLineListener(...), getCurrentLine(), setInsertMode(boolean), setPrompt(String) / getPrompt(), writePrompt(); nested event LineEvent.
  • ITerminalClipboard — clipboard control: setUseSystemClipboard(UseSystemClipboard), setCopySelection(boolean), setPasteWithRightClick(boolean), setPasteWithMiddleClick(boolean); nested enum UseSystemClipboard (FALSE, WRITE, READWRITE).
  • ITerminalFit — fit(), setFitOnResize(boolean), isFitOnResize().
  • ITerminalOptions — terminal configuration: fonts, cursor, setTheme(TerminalTheme), setScrollback(int), renderer type, accessibility, and more.
  • TerminalTheme / TerminalHistory — theme (color scheme) and command-history support.

For the full API surface, browse the published JavaDoc.

Demo

A live demo is available at addonsv25.flowingcode.com/xterm. To run the demo locally:

git clone https://github.com/FlowingCode/XTermConsoleAddon.git
cd XTermConsoleAddon
mvn clean install jetty:run

Then open http://localhost:8080/.

Source code

XTermConsoleAddon on GitHub — distributed under Apache License 2.0.