Table of Contents

Ratatui

Ratatui Website · API Docs · Examples · Changelog · Breaking Changes

Contributing · Report a bug · Request a Feature · Create a Pull Request

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.

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]);
}

Contributing

In order to organize ourselves, we currently use a Discord server,
feel free to join and come chat! There is also a Matrix bridge available at
#ratatui:matrix.org.

We have also recently launched the Ratatui Forum, For bugs and features, we rely on GitHub.
Please Report a bug, Request a Feature or Create a Pull Request.

Please make sure you read the contributing guidelines, especially if you are
interested in working on a PR or issue opened in the previous repository.

Built with Ratatui

Ratatui has a number of built-in widgets, as well
as many contributed by external contributors. Check out the Showcase
section of the website, or the awesome-ratatui repo
for a curated list of awesome apps/libraries built with ratatui!

Alternatives

You might want to checkout Cursive or
iocraft for an alternative solutions
to build text user interfaces in Rust.

Acknowledgments

None of this could be possible without Florian Dehau who originally
created tui-rs which inspired many Rust TUIs.

Special thanks to Pavel Fomchenkov for his work in designing an
awesome logo for the ratatui project and ratatui organization.

License

MIT

kardwen/ratatui