Crate tui

source ·
Expand description

tui is a library used to build rich terminal users interfaces and dashboards.

Get started

Adding tui as a dependency

[dependencies]
tui = "0.16"
termion = "1.5"

The crate is using the termion backend by default but if for example you want your application to work on Windows, you might want to use the crossterm backend instead. This can be done by changing your dependencies specification to the following:

[dependencies]
crossterm = "0.20"
tui = { version = "0.16", default-features = false, features = ['crossterm'] }

The same logic applies for all other available backends.

Creating a Terminal

Every application using tui should start by instantiating a Terminal. It is a light abstraction over available backends that provides basic functionalities such as clearing the screen, hiding the cursor, etc.

use std::io;
use tui::Terminal;
use tui::backend::TermionBackend;
use termion::raw::IntoRawMode;

fn main() -> Result<(), io::Error> {
    let stdout = io::stdout().into_raw_mode()?;
    let backend = TermionBackend::new(stdout);
    let mut terminal = Terminal::new(backend)?;
    Ok(())
}

If you had previously chosen crossterm as a backend, the terminal can be created in a similar way:

use std::io;
use tui::Terminal;
use tui::backend::CrosstermBackend;

fn main() -> Result<(), io::Error> {
    let stdout = io::stdout();
    let backend = CrosstermBackend::new(stdout);
    let mut terminal = Terminal::new(backend)?;
    Ok(())
}

You may also refer to the examples to find out how to create a Terminal for each available backend.

Building a User Interface (UI)

Every component of your interface will be implementing the Widget trait. The library comes with a predefined set of widgets that should meet most of your use cases. You are also free to implement your own.

Each widget follows a builder pattern API providing a default configuration along with methods to customize them. The widget is then rendered using Frame::render_widget which takes your widget instance and an area to draw to.

The following example renders a block of the size of the terminal:

use std::io;
use termion::raw::IntoRawMode;
use tui::Terminal;
use tui::backend::TermionBackend;
use tui::widgets::{Widget, Block, Borders};
use tui::layout::{Layout, Constraint, Direction};

fn main() -> Result<(), io::Error> {
    let stdout = io::stdout().into_raw_mode()?;
    let backend = TermionBackend::new(stdout);
    let mut terminal = Terminal::new(backend)?;
    terminal.draw(|f| {
        let size = f.size();
        let block = Block::default()
            .title("Block")
            .borders(Borders::ALL);
        f.render_widget(block, size);
    })?;
    Ok(())
}

Layout

The library comes with a basic yet useful layout management object called Layout. As you may see below and in the examples, the library makes heavy use of the builder pattern to provide full customization. And Layout is no exception:

use std::io;
use termion::raw::IntoRawMode;
use tui::Terminal;
use tui::backend::TermionBackend;
use tui::widgets::{Widget, Block, Borders};
use tui::layout::{Layout, Constraint, Direction};

fn main() -> Result<(), io::Error> {
    let stdout = io::stdout().into_raw_mode()?;
    let backend = TermionBackend::new(stdout);
    let mut terminal = Terminal::new(backend)?;
    terminal.draw(|f| {
        let chunks = Layout::default()
            .direction(Direction::Vertical)
            .margin(1)
            .constraints(
                [
                    Constraint::Percentage(10),
                    Constraint::Percentage(80),
                    Constraint::Percentage(10)
                ].as_ref()
            )
            .split(f.size());
        let block = Block::default()
             .title("Block")
             .borders(Borders::ALL);
        f.render_widget(block, chunks[0]);
        let block = Block::default()
             .title("Block 2")
             .borders(Borders::ALL);
        f.render_widget(block, chunks[1]);
    })?;
    Ok(())
}

This let you describe responsive terminal UI by nesting layouts. You should note that by default the computed layout tries to fill the available space completely. So if for any reason you might need a blank space somewhere, try to pass an additional constraint and don’t use the corresponding area.

Re-exports

pub use self::terminal::Frame;
pub use self::terminal::Terminal;
pub use self::terminal::TerminalOptions;
pub use self::terminal::Viewport;

Modules

style contains the primitives used to control how your user interface will look.
Primitives for styled text.
widgets is a collection of types that implement Widget or StatefulWidget or both.