v0.21

New backend: `termwiz`

ratatui supports a new backend called termwiz which is a “Terminal Wizardry” crate that powers wezterm.

To use it, enable the termwiz feature in Cargo.toml:

[dependencies.ratatui]
version = "0.21.0"
features = ["termwiz"]
default-features = false

Then you can utilize TermwizBackend object for creating a terminal. Here is a simple program that shows a text on the screen for 5 seconds using ratatui + termwiz:

use ratatui::{backend::TermwizBackend, widgets::Paragraph, Terminal};
use std::{
    error::Error,
    thread,
    time::{Duration, Instant},
};

fn main() -> Result<(), Box<dyn Error>> {
    let backend = TermwizBackend::new()?;
    let mut terminal = Terminal::new(backend)?;
    terminal.hide_cursor()?;

    let now = Instant::now();
    while now.elapsed() < Duration::from_secs(5) {
        terminal.draw(|f| f.render_widget(Paragraph::new("termwiz example"), f.size()))?;
        thread::sleep(Duration::from_millis(250));
    }

    terminal.show_cursor()?;
    terminal.flush()?;
    Ok(())
}

A calendar widget has been added which was originally a part of the extra-widgets repository.

Since this new widget depends on time crate, we gated it behind widget-calendar feature to avoid an extra dependency:

[dependencies.ratatui]
version = "0.21.0"
features = ["widget-calendar"]

Here is the example usage:

Monthly::new(
    time::Date::from_calendar_date(2023, time::Month::January, 1).unwrap(),
    CalendarEventStore::default(),
)
.show_weekdays_header(Style::default())
.show_month_header(Style::default())
.show_surrounding(Style::default()),

Results in:

     January 2023
 Su Mo Tu We Th Fr Sa
  1  2  3  4  5  6  7
  8  9 10 11 12 13 14
 15 16 17 18 19 20 21
 22 23 24 25 26 27 28
 29 30 31  1  2  3  4

Circle widget has been added with the use-case of showing an accuracy radius on the world map.

Here is an example of how to use it with Canvas:

Canvas::default()
    .paint(|ctx| {
        ctx.draw(&Circle {
            x: 5.0,
            y: 2.0,
            radius: 5.0,
            color: Color::Reset,
        });
    })
    .marker(Marker::Braille)
    .x_bounds([-10.0, 10.0])
    .y_bounds([-10.0, 10.0]),

Results in:

 ⡠⠤⢤⡀
⢸⡁  ⡧
 ⠑⠒⠚⠁

This was a highly requested feature and the original implementation was done by @fdehau himself. Folks at Atuin completed the implementation and we are happy to finally have this incorporated in the new release!

An inline viewport refers to a rectangular section of the terminal window that is set aside for displaying content.

In the repository, there is an example that simulates downloading multiple files in parallel: https://github.com/ratatui-org/ratatui/blob/main/examples/inline.rs

Block: title on bottom

Before you could only put the title on the top row of a Block. Now you can put it on the bottom row! Revolutionary.

For example, place the title on the bottom and center:

Paragraph::new("ratatui")
    .alignment(Alignment::Center)
    .block(
        Block::default()
            .title(Span::styled("Title", Style::default()))
            .title_on_bottom()
            .title_alignment(Alignment::Center)
            .borders(Borders::ALL),
    )

Results in:

┌─────────────────────┐
│       ratatui       │
│                     │
└────────Title────────┘

Block: support adding padding

If we want to render a widget inside a Block with a certain distance from its borders, we need to create another Layout element based on the outer Block, add a margin and render the Widget into it. Adding a padding property on the block element skips the creation of this second Layout.

This property works especially when rendering texts, as we can just create a block with padding and use it as the text wrapper:

let block = Block::default()
    .borders(Borders::ALL)
    .padding(Padding::new(1, 1, 2, 2));
let paragraph = Paragraph::new("example paragraph").block(block);
f.render_widget(paragraph, area);

Rendering another widget should be easy too, using the .inner method:

let block = Block::default().borders(Borders::ALL).padding(Padding {
    left: todo!(),
    right: todo!(),
    top: todo!(),
    bottom: todo!(),
});
let inner_block = Block::default().borders(Borders::ALL);
let inner_area = block.inner(area);

f.render_widget(block, area);
f.render_widget(inner_block, inner_area);
f.render_widget(paragraph, area);

Text: display secure data

A new type called Masked is added for text-related types for masking data with a mask character. The example usage is as follows:

Line::from(vec![
    Span::raw("Masked text: "),
    Span::styled(
        Masked::new("password", '*'),
        Style::default().fg(Color::Red),
    ),
])

Results in:

Masked text: ********

`border!` macro

A border! macro has been added that takes TOP, BOTTOM, LEFT, RIGHT, and ALL and returns a Borders object.

An empty border!() call returns NONE.

For example:

border!(ALL)
border!(LEFT, RIGHT)
border!()

This is gated behind a macros feature flag to ensure short build times. To enable it, update Cargo.toml as follows:

[dependencies.ratatui]
version = "0.21.0"
features = ["macros"]

Going forward, we will most likely put the new macros behind macros feature as well.

Color: support conversion from `String`

Have you ever needed this conversion?

"black" => Color::Black,
"red" => Color::Red,
"green" => Color::Green,
// etc.

Don’t worry, we got you covered:

Color::from_str("lightblue") // Color::LightBlue
Color::from_str("10")        // Color::Indexed(10)
Color::from_str("#FF0000")   // Color::Rgb(255, 0, 0)

`Spans` -> `Line`

Line is a significantly better name over Spans as the plural causes confusion and the type really is a representation of a line of text made up of spans.

So, Spans is renamed as Line and a deprecation notice has been added.

See https://github.com/ratatui-org/ratatui/pull/178 for more discussion.

Other features

List now has a len() method for returning the number of items
Sparkline now has a direction() method for specifying the render direction (left to right / right to left)
Table and List states now have offset() and offset_mut() methods
Expose the test buffer (TestBackend) with Display implementation

New apps

Here is the list of applications that has been added:

oxycards: quiz card application built within the terminal.
twitch-tui: twitch chat in the terminal.
tenere: TUI interface for LLMs.

Also, we moved APPS.md file to the Wiki so check it out for more applications built with ratatui!

Migration from `tui-rs`

We put together a migration guide at the Wiki: Migrating from TUI

Also, the minimum supported Rust version is 1.65.0

Contributing

Any contribution is highly appreciated! There are contribution guidelines for getting started.

Feel free to submit issues and throw in ideas!

If you are having a problem with ratatui or want to contribute to the project or just want to chit-chat, feel free to join our Discord server!

Ratatui Book

v0.21

New backend: `termwiz`

New widget: Calendar

New widget: Circle

Inline Viewport

Block: title on bottom

Block: support adding padding

Text: display secure data

`border!` macro

Color: support conversion from `String`

`Spans` -> `Line`

Other features

New apps

Migration from `tui-rs`

Contributing