Crate textual_rs 

textual-rs — a Rust port of the Textual Python TUI framework.

Build beautiful terminal UIs in Rust: declare widgets, style with CSS, react to events, and get a polished result on any terminal.

Features

• 22+ built-in widgets — buttons, inputs, tables, trees, tabs, markdown, and more
• CSS styling engine — TCSS stylesheets with selectors, pseudo-classes, and specificity cascade
• Theme system — 7 built-in themes with $variable support and lighten/darken modifiers
• Reactive state — Reactive<T> signals with automatic re-rendering
• Flexbox & grid layout — powered by Taffy
• Async workers — background tasks with progress streaming
• Headless testing — TestApp + Pilot for automated UI tests

Quick Start

Add to your Cargo.toml:

[dependencies]
textual-rs = "0.3"

Create a minimal application:

use textual_rs::{App, Widget, Label, Header, Footer};
use textual_rs::widget::context::AppContext;
use ratatui::{buffer::Buffer, layout::Rect};

struct MyScreen;
impl Widget for MyScreen {
    fn widget_type_name(&self) -> &'static str { "MyScreen" }
    fn compose(&self) -> Vec<Box<dyn Widget>> {
        vec![
            Box::new(Header::new("My App")),
            Box::new(Label::new("Hello, world!")),
            Box::new(Footer),
        ]
    }
    fn render(&self, _: &AppContext, _: Rect, _: &mut Buffer) {}
}

fn main() -> anyhow::Result<()> {
    App::new(|| Box::new(MyScreen)).run()
}

Add CSS styling with theme variables:

let mut app = App::new(|| Box::new(MyScreen))
    .with_css("
        MyScreen { background: $background; color: $foreground; }
        Header { background: $panel; color: $primary; }
    ");
// app.run()?;

Press F5 at runtime to cycle through built-in themes (textual-dark, textual-light, tokyo-night, nord, gruvbox, dracula, catppuccin). Use App::with_theme_cycle_key to rebind it.

See the User Guide and CSS Reference for full documentation.

Re-exports

pub use app::App;

pub use event::AppEvent;

pub use testing::pilot::Pilot;

pub use testing::TestApp;

pub use widget::Widget;

pub use widget::WidgetId;

pub use hyperlink::LinkedSpan;

pub use hyperlink::LinkedLine;

pub use command::CommandPalette;

pub use command::CommandRegistry;

pub use widget::button::Button;

pub use widget::button::ButtonVariant;

pub use widget::checkbox::Checkbox;

pub use widget::collapsible::Collapsible;

pub use widget::data_table::ColumnDef;

pub use widget::data_table::DataTable;

pub use widget::footer::Footer;

pub use widget::header::Header;

pub use widget::input::Input;

pub use widget::label::Label;

pub use widget::layout::Horizontal;

pub use widget::layout::Vertical;

pub use widget::list_view::ListView;

pub use widget::loading_indicator::LoadingIndicator;

pub use widget::log::Log;

pub use widget::markdown::Markdown;

pub use widget::placeholder::Placeholder;

pub use widget::progress_bar::ProgressBar;

pub use widget::radio::RadioButton;

pub use widget::radio::RadioSet;

pub use widget::rich_log::RichLog;

pub use widget::scroll_region::ScrollContent;

pub use widget::scroll_region::ScrollRegion;

pub use widget::scroll_view::ScrollView;

pub use widget::select::Select;

pub use widget::sparkline::Sparkline;

pub use widget::switch::Switch;

pub use widget::tabs::TabbedContent;

pub use widget::tabs::Tabs;

pub use widget::screen::ModalScreen;

pub use widget::text_area::TextArea;

pub use widget::tree_view::Tree;

pub use widget::tree_view::TreeNode;

pub use worker::WorkerProgress;

pub use worker::WorkerResult;

Modules

animation

Lightweight tweening animation system.

app

Core application runtime: event loop, widget tree management, and rendering.

canvas

Sub-cell rendering primitives using Unicode half-block and block characters.

command

Command palette and registry for discoverable application actions.

css

TCSS (Textual CSS) styling engine: parsing, cascade, theming, and rendering.

event

Event system: application events, message passing, key bindings, and timers.

hyperlink

OSC 8 hyperlink support for textual-rs widgets.

layout

Layout engine: Taffy-backed flexbox/grid bridge, hit testing, and style mapping.

reactive

Reactive state primitives: Reactive<T> signals that trigger re-renders on change.

terminal

Terminal setup and teardown: raw mode, alternate screen, and mouse capture.

testing

Headless testing infrastructure for automated UI tests.

widget

Widget trait, widget ID type, and all built-in widget implementations.

worker

Async worker tasks: background computation with progress streaming and result delivery.

Attribute Macros

widget_impl

Attribute macro for impl Widget for MyStruct blocks.

Derive Macros

Widget

Derive macro that generates inherent __ helper methods on the struct.