Getting Started with tui.rs – A Cross‑Platform Rust Terminal UI Library

Command‑line tools are a developer’s secret weapon; this article introduces the Rust library tui.rs , a cross‑platform solution for creating sleek terminal user interfaces.

1. Installation

Add the library to your Cargo.toml just like any other Rust dependency:

[dependencies]
tui = "0.17"
crossterm = "0.22"

If you want the official examples, clone the repository:

$ git clone https://github.com/fdehau/tui-rs.git
$ cd tui-rs
$ cargo run --example demo

2. Quick Start

2.1 Overview of Modules

tui.rs provides several modules that implement the Widget or StatefulWidget traits:

backend – backend for managing terminal output

layout – layout management for UI components

style – styling of UI elements

symbols – point styles for charts

text – styled text handling

widgets – collection of ready‑made UI widgets

The following code creates a minimal tui interface:

use crossterm::{
    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode},
    execute,
    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
};
use std::{io, time::Duration};
use tui::{
    backend::{Backend, CrosstermBackend},
    layout::{Alignment, Constraint, Direction, Layout},
    style::{Color, Modifier, Style},
    text::{Span, Spans, Text},
    widgets::{Block, Borders, Paragraph, Widget},
    Frame, Terminal,
};

struct App {
    url: String, // store data or UI state
}

fn main() -> Result<(), io::Error> {
    enable_raw_mode()?;
    let mut stdout = io::stdout();
    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
    let backend = CrosstermBackend::new(stdout);
    let mut terminal = Terminal::new(backend)?;
    let mut app = App { url: String::from(r"https://hellogithub.com/") };
    run_app(&mut terminal, app)?;
    disable_raw_mode()?;
    execute!(terminal.backend_mut(), LeaveAlternateScreen, DisableMouseCapture)?;
    terminal.show_cursor()?;
    Ok(())
}

fn run_app
(terminal: &mut Terminal
, mut app: App) -> io::Result<()> {
    loop {
        terminal.draw(|f| ui(f, &mut app))?;
        if crossterm::event::poll(Duration::from_secs(1))? {
            if let Event::Key(key) = event::read()? {
                match key.code {
                    KeyCode::Char('q') => break,
                    _ => {}
                }
            }
        }
    }
    Ok(())
}

fn ui
(f: &mut Frame
, app: &mut App) {
    let chunks = Layout::default()
        .constraints([Constraint::Length(3), Constraint::Min(3)].as_ref())
        .direction(Direction::Vertical)
        .split(f.size());
    let paragraph = Paragraph::new(Span::styled(
        app.url.as_str(),
        Style::default().add_modifier(Modifier::BOLD),
    ))
    .block(Block::default().borders(Borders::ALL).title("HelloGitHub"))
    .alignment(tui::layout::Alignment::Left);
    f.render_widget(paragraph, chunks[0]);

    let paragraph = Paragraph::new("Share interesting, entry‑level open‑source projects from GitHub")
        .style(Style::default().bg(Color::White).fg(Color::Black))
        .block(Block::default().borders(Borders::ALL).title("Purpose"))
        .alignment(Alignment::Center);
    f.render_widget(paragraph, chunks[1]);
}

The program first configures the terminal, switches to an alternate screen, and enables raw mode. After the UI loop finishes, it restores the original terminal state.

2.2 Template Creation

The official examples provide a template for using tui.rs . Follow the same structure to keep your code readable: initialize components with ::default() , customize them with Block::default().borders(...) or Style::default().bg(...) , and render with f.render_widget (or f.render_stateful_widget for stateful widgets).

3. More Useful Tools Built with tui.rs

Several popular open‑source CLI projects are built on tui.rs :

Real‑time stock data viewer (https://github.com/tarkah/tickrs)

File transfer tool supporting SCP/SFTP/FTP/S3 (https://github.com/veeso/termscp)

Network monitor showing per‑process and connection usage (https://github.com/imsnif/bandwhich)

Explore these repositories for more advanced examples.

That concludes the introduction to tui.rs ; with the provided template and examples, anyone can quickly build powerful terminal UIs.