Rust

The Rust crates let you build OpenTUI apps in Rust, with no JavaScript runtime. They drive the same native renderer that Core uses: it keeps a tree of nodes, lays them out with flexbox, and draws them to the terminal.

This app shows a list of tasks and reports the one you pick. Press q to quit:

use opentui::prelude::*;

fn main() -> opentui::Result<()> {
    let app = App::new(AppOptions::default())?;
    let status = Text::new(&app, "Pick a task").fg(app.theme().muted);
    let list = Select::new(&app).options(["Build", "Test", "Ship"]).grow(1.0);
    app.root()
        .add(&View::new(&app).border(BorderStyle::Rounded).title(" Tasks ").padding(1).grow(1.0).child(&list))
        .add(&status);
    list.on_select(move |_cx, _index, option| {
        status.set_text(format!("Selected {}", option.name));
    });
    app.on_key(|cx, key| {
        if key.matches("q") {
            cx.quit();
        }
    });
    list.focus();
    app.run()
}

The other samples in this guide leave out use opentui::prelude::* and assume an app made with App::new(AppOptions::default())?.

The crates#

The crates live in packages/rust:

  • opentui is the framework: widgets, an event loop, focus, keyboard and mouse input, timers, and a test harness that needs no terminal. Most apps depend only on this crate.
  • opentui-ssh serves an app over SSH, one app per session.
  • opentui-sys is the raw C API of the native library. opentui wraps it safely, so you rarely use it directly.

The crates are not on crates.io. You depend on them through Git, pinned to a release tag, and link the native library from that same release. Install, link, and ship shows how.

Run the examples#

The examples run from the Rust workspace in a checkout of the repository. Build the native library first, as Build from a checkout describes. Then sh run.sh <name> builds an example with syntax highlighting turned on and runs it:

sh run.sh hello       # a centered card with a button and live event reports
sh run.sh showcase    # every widget: a form, a list, a live log, a file table with source, and styled text
sh run.sh effects     # color matrices, filters, and animated effects on a panel or the whole screen
sh run.sh tasks       # a task list you move through and toggle
sh run.sh native      # the native layer and host, without the framework
sh run.sh workbench   # a native-layer build queue with live progress and a debug pane
sh run.sh terminal    # your shell in a terminal widget, beside a notes field
sh run.sh split       # a prompt in a footer that writes its lines to the scrollback above
sh run.sh video       # a video player; `cargo run --example video -- file.mp4` plays your own file
sh run.sh chat        # an SSH chat server on 127.0.0.1:2222: run `ssh -p 2222 localhost` per participant
sh run.sh tasks static

Read on#

Changes0.9.3, 0.9.2, 0.9.0
0.9.3
native: Programs on x64 Windows that link the static library with the static MSVC C runtime and also call strtod now link without the LNK2005 error for strtold. The library keeps its bundled MinGW runtime copies private, and MinGW programs that call strtold still work. (#2157)
0.9.2
native: If the native library is missing outside an OpenTUI checkout, the opentui-sys build script names the release archive to extract, such as opentui-native-v0.9.2-linux-x64.zip, instead of bun run build. Set OPENTUI_LIB_HINT to replace this advice with your own setup step. (#2150)
0.9.0
rust: The experimental crates opentui-sys, opentui, and opentui-ssh moved into the OpenTUI repository and are not published, so depend on them by Git revision. On Linux and macOS they link the static library by default; for the shared library, turn off default features in every crate that depends on them. On Windows, ship opentui.dll beside the app. (#1946, #1949, #1984, #1992)
rust: Markdown parses with the native engine and follows CommonMark and GFM, so rules and setext headings can render differently. Its code fences now wrap by word; a standalone Code still does not wrap. Input::max_length counts UTF-16 units, as Core does. (#2049, #2089, #2017)
rust: An app’s priority-0 highlight paints under syntax colors. Textareas that share one style table share one syntax theme: the one set last on any of them. After clear_highlights, a theme change brings syntax colors back only at the next edit. (#2026, #2030)
rust: On Unix, Ctrl+Z stops the app’s whole process group, and a suspend or release drops the rest of the input from that read. On Windows, Host::release hands the terminal to its task as on Unix. ScrollbackSurface::commit_rows fails after a change of width or width method until the surface renders again. (#1950, #1958, #2043, #2082)
rust: App::on_animation_tick and Widget::on_animation_tick run animations on Core’s shared clock, so animations with equal rates tick in the same frames. An animation bound to a widget parks while the widget is hidden, detached, or clipped out of view. AnimationTick::follow adds a widget to an animation, and Widget::downgrade returns a WeakWidget that does not keep the widget alive. (#2120, #2134)
rust: ScrollBox::on_scroll reports each move of a scroll box once, with its position and cause. (#2129)
rust: Code::finish() frees the parse tree of a view whose text stopped growing, and the next change parses again. A transcript with 100 written files uses 36 MB less heap. (#2126)
rust: Code, Diff, and Textarea views no longer wrap their text at width 0 before their first frame, and Code views and Diff rows share their theme and signs instead of copying them. 100 Code views mounted before their first draw take 20 MB instead of 438 MB. (#2124, #2123)
rust: Timers, deferred tasks, and quit() calls that a frame starts run on time in an otherwise idle app. Before, they waited for the next unrelated wakeup, so a headless app could fail to end. (#2118)
rust: A split-footer app whose terminal does not answer the cursor-position query sleeps between startup replies instead of using a full core for five seconds. (#2122)
rust: An app that ends with deferred tasks, timers, handlers, or spawned tasks still queued no longer panics or hangs in teardown. (#2132, #2120)