cursive

Cursive is a text user interface (TUI) library for Rust that lets you build interactive terminal applications from a tree of composable views. It ships with a wide set of built-in views — dialogs, buttons, text fields, scrollable panels, select lists, menus, and more — that nest, wrap, and style together to construct complex UIs without touching the terminal driver directly.

Under the hood, Cursive abstracts over multiple terminal backends (crossterm by default, plus ncurses, pancurses, termion, and BearLibTerminal), so the same application code renders consistently across Linux, macOS, and Windows terminals. Its workspace splits the batteries-included cursive crate from cursive-core, the reusable engine that third-party crates build new views and backends on top of without depending on any specific terminal implementation.

What You Get

• A composable view tree (Dialog, LinearLayout, StackView, ScrollView, SelectView, TextView, EditView, and ~30 more) that nest to build full UIs
• Pluggable backends (crossterm by default, plus ncurses, pancurses, termion, BearLibTerminal) so the same app runs across terminals and OSes
• A theming system with TOML-based color and border styles and runtime theme switching
• A callback-driven event and Tab-based focus system for routing keyboard and mouse input through the view tree
• An async callback sink (cb_sink) for pushing UI updates in from background threads

Common Use Cases

• Building full-screen terminal dashboards and monitoring tools
• Writing interactive CLI configuration wizards and menus
• Creating terminal-based games and puzzle apps
• Building admin/ops tools like process managers or log viewers that need a richer UI than plain stdout
• Prototyping UI flows quickly before committing to a GUI or web frontend

Under The Hood

Architecture Cursive splits into a workspace of crates: cursive-core (the reusable engine — event loop, View trait, backend abstraction, theming) and cursive (the batteries-included crate that re-exports cursive-core and wires up concrete backends like crossterm). The central Cursive struct owns a RootView type alias (OnEventView<ScreensView<StackView>>), a menubar, a crossbeam channel pair for the cb_sink/cb_source async callback queue, and a Box<dyn Any> slot for user data. Every UI element implements the View trait with a required-size/layout/draw/on_event/take_focus contract; around 39 built-in view types compose by wrapping and nesting rather than inheritance, and views forward unhandled events up through parents for a Tab-based focus system. Backends sit behind a backend::Backend trait with concrete implementations for crossterm, ncurses/pancurses, termion, BearLibTerminal, and a puppet backend used for testing, selected via Cargo features so swapping terminals requires no application code changes. If the View trait’s contract changed, every built-in view and every third-party view crate would need updates — a meaningful but well-contained blast radius given the crate split.

Tech Stack A Rust 2024-edition Cargo workspace of four published crates (cursive, cursive-core, cursive-macros, cursive-syntect). Core dependencies include crossbeam-channel for the cross-thread callback queue, ahash and enumset for fast internal bookkeeping, unicode-segmentation and unicode-width for correct text layout, and parking_lot for the root struct’s locking. Terminal backends are optional Cargo features (crossterm as default, plus ncurses/pancurses C bindings, termion, and BearLibTerminal), with additional feature-gated integrations for TOML theme files, markdown-to-StyledString parsing, ANSI text parsing, and a data-driven builder module backed by the inventory crate. A companion cursive-syntect crate adds syntax-highlighted text views. CI runs cargo check/build/test across the full feature matrix on GitHub Actions.

Code Quality Unit tests are colocated across the workspace (23 files contain #[test] blocks, including dedicated suites like utils/lines/simple/tests.rs), plus an integration-style select_test example that CI runs explicitly, and a purpose-built puppet backend for driving views in tests without a real terminal. CI exercises the full feature combination matrix, not just defaults, which catches feature-interaction breakage. rustfmt.toml pins formatting conventions, though no clippy step is wired into CI. The public API favors Result/Option over panics (view lookups return a typed ViewNotFound, builder parsing has dedicated error types), and #![deny(missing_docs)] enforces documentation coverage on every public item in cursive-core.

API Design The library reads as idiomatic Rust: chainable builder-style methods (.title(), .button(), .wrap_with()) let simple apps stay a handful of lines, while the same View trait scales to custom, hand-rolled views for complex cases. Getting started requires only cursive::default() and add_layer(), and 56 runnable examples plus a three-part tutorial in doc/ cover most common patterns. Consistent naming (*View types, with/wrap_with combinators) makes the API predictable once the view-tree mental model clicks, though that model itself — required_size/layout contracts, focus propagation, event bubbling — is the main upfront learning cost for newcomers coming from immediate-mode UI libraries.