tui-textarea

tui-textarea is a Rust crate that drops a fully-featured, multi-line text editor widget into a ratatui or tui-rs terminal application, similar to the HTML <textarea> element. Rather than forcing developers to build cursor movement, selection, undo/redo, and line editing from scratch, it ships a TextArea struct that owns editor state and renders as a standard widget, so it slots directly into an existing render loop.

The crate is backend-agnostic — crossterm, termion, and termwiz are all supported behind feature flags, alongside both the actively maintained ratatui fork and the original tui-rs crate — and it ships Emacs-style key bindings out of the box while still allowing fully custom key mapping. It is a common building block for TUI editors, REPLs, config prompts, and any terminal tool that needs more than a single-line input field.

What You Get

• A TextArea struct that manages editor state (lines, cursor position, selection, yank buffer) independently of any specific backend
• Default Emacs-like key bindings (Ctrl+A/E, Ctrl+K/J, Alt+F/B, etc.) applied via a single TextArea::input() call, with full override support for custom key maps
• Built-in undo/redo history that groups related edits (e.g. consecutive character inserts) into single undoable steps
• Regex-based text search (behind the search feature) with match highlighting and next/previous navigation
• Backend support for crossterm, termion, and termwiz, plus a no-backend mode for custom input handling, selectable via Cargo feature flags
• Optional serde feature for serializing and restoring editor state, and an arbitrary feature for fuzz testing integration

Common Use Cases

• Embedding a multi-line code or config editor inside a terminal application (e.g. a commit-message editor or in-app file editor)
• Building single-line input forms with custom validation, such as numeric or password fields, by constraining a TextArea to one line
• Adding a Vim-style modal editing mode on top of the widget’s raw key input for terminal tools that want modal editing
• Rendering multiple independent textareas in one screen (e.g. split-pane editors or multi-field forms) since each TextArea instance is self-contained
• Providing a search-and-filter text input inside TUI dashboards or log viewers using the built-in regex search feature

Under The Hood

Architecture The crate is organized as a set of focused modules under src/: textarea.rs holds the central TextArea struct and its editing/rendering methods, cursor.rs defines cursor-movement semantics, history.rs implements a VecDeque-backed undo/redo log that groups related EditKind variants (insert/delete char, newline, string, chunk) into single undoable steps, widget.rs implements the ratatui/tui-rs Widget trait and tracks the last-rendered viewport via an atomic-packed Viewport struct for scroll calculations, input/ translates each backend’s native key event type into a shared Input/Key representation, and search.rs layers regex matching on top of the line buffer behind a feature flag. State flows one way: backend key events enter through TextArea::input(), are normalized, mutate the line buffer and cursor/selection state, and the same immutable &TextArea reference is handed to the renderer on the next frame — there is no internal event loop or app lifecycle, so the crate stays a pure, embeddable state machine rather than a framework.

Tech Stack The crate is pure Rust (edition 2021, MSRV 1.56.1) with unicode-width as its only non-optional dependency for correct multi-byte character width handling. Everything else is opt-in via Cargo feature flags: ratatui (0.29) or tui (0.19, the older tui-rs fork) as mutually exclusive rendering backends, crossterm/termion/termwiz for terminal I/O, regex for the search feature, serde for state (de)serialization, and arbitrary for fuzz-testing support. A separate bench workspace member and a fuzz/ directory (cargo-fuzz) provide performance and property-based robustness testing outside the main crate.

Code Quality The repository has substantial test coverage — roughly 2,300 lines across six files under tests/ (textarea.rs, cursor.rs, history.rs, input.rs, search.rs, serde.rs) exercising editing, cursor movement, undo/redo, key input, search, and serialization paths, run through a GitHub Actions CI workflow with Codecov reporting. The crate forbids unsafe code (#![forbid(unsafe_code)]) and warns on stray dbg!/print! macros at the crate root, uses Result-free panics only via debug_assert! guards in internal invariants, and keeps naming and module boundaries consistent throughout. No unwrap-heavy public API surface was observed in the core editing paths.

API Design The public surface is intentionally small: TextArea implements Default, From<Iterator<Item=Into<String>>>, and FromIterator, so an editor can be constructed from an empty state, a Vec<String>, or lines read from a file via BufReader. A single TextArea::input() method accepts backend-native key events directly (when the corresponding feature is enabled) and applies default Emacs-style key mappings, while advanced users can bypass this and call lower-level editing methods directly for fully custom key handling. The crate documents this trade-off clearly in its README with a full default key-mapping table and eight runnable examples covering minimal setup, a full file editor, single-line/password inputs, split panes, and Vim emulation, keeping the barrier to a working integration low.