Crate ratatuiCopy item path

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;

fn main() -> std::io::Result<()> {
    ratatui::run(|mut terminal| {
        loop {
            terminal.draw(|frame| frame.render_widget("Hello World!", frame.area()))?;
            if event::read()?.is_key_press() {
                break Ok(());
            }
        }
    })
}

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 Ratatui tutorial sections in the Ratatui Website and the various Examples. There are also several starter Templates available to help you get started quickly with common patterns.

§Other documentation

• Ratatui Website - explains the library’s concepts and provides step-by-step tutorials
• Tutorials - step-by-step guides including Hello Ratatui tutorial and Counter App
• Recipes - practical how-to guides for common tasks and patterns
• FAQ - frequently asked questions and answers
• Templates - pre-built project templates using Cargo Generate
• Showcase - a gallery of applications and widgets built with Ratatui
• Ratatui Forum - a place to ask questions and discuss the library
• API Docs - the full API documentation for the library on docs.rs.
• Examples - a collection of examples that demonstrate how to use the library.
• Contributing - Please read this if you are interested in contributing to the project.
• Changelog - generated by git-cliff utilizing Conventional Commits.
• Breaking Changes - a list of breaking changes in the library.

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.

§Getting Help

If you need help or have questions, check out our FAQ for common questions and solutions. You can also join our community on Discord, Matrix, or post on our Forum for assistance and discussions.

§Crate Organization

Starting with Ratatui 0.30.0, the project was reorganized into a modular workspace to improve compilation times, API stability, and dependency management. Most applications should continue using this main ratatui crate, which re-exports everything for convenience:

• ratatui: Main crate with complete functionality (recommended for apps)
• ratatui-core: Core traits and types for widget libraries
• ratatui-widgets: Built-in widget implementations
• Backend crates: ratatui-crossterm, ratatui-termion, ratatui-termwiz
• ratatui-macros: Macros for simplifying the boilerplate

For application developers: No changes needed - continue using ratatui as before.

For widget library authors: Consider depending on ratatui-core instead of the full ratatui crate for better API stability and reduced dependencies.

See ARCHITECTURE.md for detailed information about the crate organization and design decisions.

§Writing Applications

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 (see the init module for convenient initialization functions)
• A main loop that:
  • Draws the UI
  • Handles input events
• Restore the terminal state

§Initialize and restore the terminal

The simplest way to initialize and run a terminal application is to use the run() function, which handles terminal initialization, restoration, and panic hooks automatically:

fn main() -> std::io::Result<()> {
    ratatui::run(|mut terminal| {
        loop {
            terminal.draw(render)?;
            if should_quit()? {
                break Ok(());
            }
        }
    })
}

fn render(frame: &mut ratatui::Frame) {
    // ...
}

fn should_quit() -> std::io::Result<bool> {
    // ...
}

For more control over initialization and restoration, you can use init() and restore():

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

fn run_app(terminal: &mut ratatui::DefaultTerminal) -> std::io::Result<()> {
    loop {
        terminal.draw(render)?;
        if should_quit()? {
            break Ok(());
        }
    }
}

Note that when using init() and restore(), it’s important to use a separate function for the main loop to ensure that restore() is always called, even if the ? operator causes early return from an error.

For more detailed information about initialization options and when to use each function, see the init module documentation.

§Manual Terminal and Backend Construction

Before the convenience functions were introduced in version 0.28.1 (init()/restore()) and 0.30.0 (run()), applications constructed Terminal and Backend instances manually. This approach is still supported for applications that need fine-grained control over initialization. See the Terminal and backend module documentation for details.

See the backend module and the Backends section of the Ratatui Website for more info on the alternate screen and raw mode. Learn more about different backend options in the Backend Comparison guide.

§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 and the Widget Recipes for more info on creating effective UIs.

The closure passed to the Terminal::draw method should handle the rendering of a full frame. For guidance on setting up the terminal before drawing, see the init module documentation.

use ratatui::Frame;
use ratatui::widgets::Paragraph;

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

fn render(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 conceptual information. 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, and check out the Layout Recipes for practical examples.

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

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, and explore the Styling Recipes for creative examples.

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

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, the macros feature which provides some useful macros and layout-cache which speeds up layout cache calculations in std-enabled environments.

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

• crossterm (enabled by default) — enables the CrosstermBackend backend and adds a dependency on crossterm.
• termion — enables the TermionBackend backend and adds a dependency on termion.
• termwiz — enables the TermwizBackend backend and adds a dependency on termwiz.
• std (enabled by default) — enables std

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.
• layout-cache (enabled by default) — enables layout cache
• 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).
• macros (enabled by default) — enables the macros module which provides some useful macros for creating spans, lines, text, and layouts
• all-widgets (enabled by default) — enables all widgets.

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

• widget-calendar (enabled by default) — enables the calendar widget module.

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 Crossterm and Termwiz backends, 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.