Crate ratatui

source
Expand description

Demo

§Ratatui

Ratatui is a crate for cooking up terminal user interfaces in Rust. It is a lightweight library that provides a set of widgets and utilities to build complex Rust TUIs. Ratatui was forked from the tui-rs crate in 2023 in order to continue its development.

§Quickstart

Add ratatui and crossterm as dependencies to your cargo.toml:

cargo add ratatui crossterm

Then you can create a simple “Hello World” application:

use crossterm::event::{self, Event};
use ratatui::{text::Text, Frame};

fn main() {
    let mut terminal = ratatui::init();
    loop {
        terminal.draw(draw).expect("failed to draw frame");
        if matches!(event::read().expect("failed to read event"), Event::Key(_)) {
            break;
        }
    }
    ratatui::restore();
}

fn draw(frame: &mut Frame) {
    let text = Text::raw("Hello World!");
    frame.render_widget(text, frame.area());
}

The full code for this example which contains a little more detail is in the Examples directory. For more guidance on different ways to structure your application see the Application Patterns and Hello World tutorial sections in the Ratatui Website and the various Examples. There are also several starter templates available in the templates repository.

§Other documentation

You can also watch the FOSDEM 2024 talk about Ratatui which gives a brief introduction to terminal user interfaces and showcases the features of Ratatui, along with a hello world demo.

§Introduction

Ratatui is based on the principle of immediate rendering with intermediate buffers. This means that for each frame, your app must render all widgets that are supposed to be part of the UI. This is in contrast to the retained mode style of rendering where widgets are updated and then automatically redrawn on the next frame. See the Rendering section of the Ratatui Website for more info.

Ratatui uses Crossterm by default as it works on most platforms. See the Installation section of the Ratatui Website for more details on how to use other backends (Termion / Termwiz).

Every application built with ratatui needs to implement the following steps:

  • Initialize the terminal
  • A main loop that:
    • Draws the UI
    • Handles input events
  • Restore the terminal state

§Initialize and restore the terminal

The Terminal type is the main entry point for any Ratatui application. It is generic over a a choice of Backend implementations that each provide functionality to draw frames, clear the screen, hide the cursor, etc. There are backend implementations for Crossterm, Termion and Termwiz.

The simplest way to initialize the terminal is to use the init function which returns a DefaultTerminal instance with the default options, enters the Alternate Screen and Raw mode and sets up a panic hook that restores the terminal in case of panic. This instance can then be used to draw frames and interact with the terminal state. (The DefaultTerminal instance is a type alias for a terminal with the crossterm backend.) The restore function restores the terminal to its original state.

fn main() -> std::io::Result<()> {
    let mut terminal = ratatui::init();
    let result = run(&mut terminal);
    ratatui::restore();
    result
}

See the backend module and the Backends section of the Ratatui Website for more info on the alternate screen and raw mode.

§Drawing the UI

Drawing the UI is done by calling the Terminal::draw method on the terminal instance. This method takes a closure that is called with a Frame instance. The Frame provides the size of the area to draw to and allows the app to render any Widget using the provided render_widget method. After this closure returns, a diff is performed and only the changes are drawn to the terminal. See the Widgets section of the Ratatui Website for more info.

The closure passed to the Terminal::draw method should handle the rendering of a full frame.

use ratatui::{widgets::Paragraph, Frame};

fn run(terminal: &mut ratatui::DefaultTerminal) -> std::io::Result<()> {
    loop {
        terminal.draw(|frame| draw(frame))?;
        if handle_events()? {
            break Ok(());
        }
    }
}

fn draw(frame: &mut Frame) {
    let text = Paragraph::new("Hello World!");
    frame.render_widget(text, frame.area());
}

§Handling events

Ratatui does not include any input handling. Instead event handling can be implemented by calling backend library methods directly. See the Handling Events section of the Ratatui Website for more info. For example, if you are using Crossterm, you can use the crossterm::event module to handle events.

use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind};

fn handle_events() -> std::io::Result<bool> {
    match event::read()? {
        Event::Key(key) if key.kind == KeyEventKind::Press => match key.code {
            KeyCode::Char('q') => return Ok(true),
            // handle other key events
            _ => {}
        },
        // handle other events
        _ => {}
    }
    Ok(false)
}

§Layout

The library comes with a basic yet useful layout management object called Layout which allows you to split the available space into multiple areas and then render widgets in each area. This lets you describe a responsive terminal UI by nesting layouts. See the Layout section of the Ratatui Website for more info.

use ratatui::{
    layout::{Constraint, Layout},
    widgets::Block,
    Frame,
};

fn draw(frame: &mut Frame) {
    use Constraint::{Fill, Length, Min};

    let vertical = Layout::vertical([Length(1), Min(0), Length(1)]);
    let [title_area, main_area, status_area] = vertical.areas(frame.area());
    let horizontal = Layout::horizontal([Fill(1); 2]);
    let [left_area, right_area] = horizontal.areas(main_area);

    frame.render_widget(Block::bordered().title("Title Bar"), title_area);
    frame.render_widget(Block::bordered().title("Status Bar"), status_area);
    frame.render_widget(Block::bordered().title("Left"), left_area);
    frame.render_widget(Block::bordered().title("Right"), right_area);
}

Running this example produces the following output:

Title Bar───────────────────────────────────
┌Left────────────────┐┌Right───────────────┐
│                    ││                    │
└────────────────────┘└────────────────────┘
Status Bar──────────────────────────────────

§Text and styling

The Text, Line and Span types are the building blocks of the library and are used in many places. Text is a list of Lines and a Line is a list of Spans. A Span is a string with a specific style.

The style module provides types that represent the various styling options. The most important one is Style which represents the foreground and background colors and the text attributes of a Span. The style module also provides a Stylize trait that allows short-hand syntax to apply a style to widgets and text. See the Styling Text section of the Ratatui Website for more info.

use ratatui::{
    layout::{Constraint, Layout},
    style::{Color, Modifier, Style, Stylize},
    text::{Line, Span},
    widgets::{Block, Paragraph},
    Frame,
};

fn draw(frame: &mut Frame) {
    let areas = Layout::vertical([Constraint::Length(1); 4]).split(frame.area());

    let line = Line::from(vec![
        Span::raw("Hello "),
        Span::styled(
            "World",
            Style::new()
                .fg(Color::Green)
                .bg(Color::White)
                .add_modifier(Modifier::BOLD),
        ),
        "!".red().on_light_yellow().italic(),
    ]);
    frame.render_widget(line, areas[0]);

    // using the short-hand syntax and implicit conversions
    let paragraph = Paragraph::new("Hello World!".red().on_white().bold());
    frame.render_widget(paragraph, areas[1]);

    // style the whole widget instead of just the text
    let paragraph = Paragraph::new("Hello World!").style(Style::new().red().on_white());
    frame.render_widget(paragraph, areas[2]);

    // use the simpler short-hand syntax
    let paragraph = Paragraph::new("Hello World!").blue().on_yellow();
    frame.render_widget(paragraph, areas[3]);
}

§Features

The crate provides a set of optional features that can be enabled in your cargo.toml file.

  • default — By default, we enable the crossterm backend as this is a reasonable choice for most applications as it is supported on Linux/Mac/Windows systems. We also enable the underline-color feature which allows you to set the underline color of text.

Generally an application will only use one backend, so you should only enable one of the following features:

The following optional features are available for all backends:

  • serde — enables serialization and deserialization of style and color types using the serde crate. This is useful if you want to save themes to a file.
  • macros — enables the border! macro.
  • palette — enables conversions from colors in the palette crate to Color.
  • scrolling-regions — Use terminal scrolling regions to make some operations less prone to flickering. (i.e. Terminal::insert_before).
  • all-widgets — enables all widgets.

Widgets that add dependencies are gated behind feature flags to prevent unused transitive dependencies. The available features are:

  • widget-calendar — enables the calendar widget module and adds a dependency on time.

The following optional features are only available for some backends:

  • underline-color (enabled by default) — enables the backend code that sets the underline color. Underline color is only supported by the CrosstermBackend backend, and is not supported on Windows 7.

The following features are unstable and may change in the future:

  • unstable — Enable all unstable features.
  • unstable-rendered-line-info — Enables the Paragraph::line_count Paragraph::line_width methods which are experimental and may change in the future. See Issue 293 for more details.
  • unstable-widget-ref — Enables the WidgetRef and StatefulWidgetRef traits which are experimental and may change in the future.
  • unstable-backend-writer — Enables getting access to backends’ writers.

Re-exports§

Modules§

  • backend
    This module provides the backend implementations for different terminal libraries.
  • buffer
    A module for the Buffer and Cell types.
  • layout
  • prelude
    A prelude for conveniently writing applications using this library.
  • style
    style contains the primitives used to control how your user interface will look.
  • symbols
  • text
    Primitives for styled text.
  • widgets
    widgets is a collection of types that implement Widget or StatefulWidget or both.

Macros§

  • assert_buffer_eqDeprecated
    Assert that two buffers are equal by comparing their areas and content.
  • bordermacros
    Macro that constructs and returns a combination of the Borders object from TOP, BOTTOM, LEFT and RIGHT.

Structs§

Enums§

  • Viewport
    Represents the viewport of the terminal. The viewport is the area of the terminal that is currently visible to the user. It can be either fullscreen, inline or fixed.

Functions§

  • initcrossterm
    Initialize a terminal with reasonable defaults for most applications.
  • init_with_optionscrossterm
    Initialize a terminal with the given options and reasonable defaults.
  • restorecrossterm
    Restores the terminal to its original state.
  • try_initcrossterm
    Try to initialize a terminal using reasonable defaults for most applications.
  • try_init_with_optionscrossterm
    Try to initialize a terminal with the given options and reasonable defaults.
  • try_restorecrossterm
    Restore the terminal to its original state.

Type Aliases§