ratatui/ratatui-macros

Ratatui Macros

ratatui-macros is a Rust crate that provides easy-to-use macros for simplifying boilerplate associated with creating UI using Ratatui.

This is an experimental playground for us to explore macros that would be useful to have in Ratatui proper.

Features

• Text macros for easily defining styled Texts, Lines, and Spans.
• Layout macros for defining Layouts with Constraints and directions.
• Table macros for creating Rows and Cells.

Getting Started

Add ratatui-macros as a dependency in your Cargo.toml:

cargo add ratatui-macros

Then, import the macros in your Rust file:

use ratatui_macros::{constraint, constraints, horizontal, line, row, span, text, vertical};

Text Macros

The [span!] macro creates raw or styled Spans.

let name = "world!";
let raw_greeting = span!("hello {name}");
let styled_greeting = span!(Style::new().green(); "hello {name}");
let colored_greeting = span!(Color::Green; "hello {name}");
let modified_greeting = span!(Modifier::BOLD; "hello {name}");

The [line!] macro creates a Line that contains a sequence of Spans. It is similar to the [vec!] macro. Each element is converted into a Span using [Into::into].

let name = "world!";
let line = line!["hello", format!("{name}")];
let line = line!["hello ", span!(Color::Green; "{name}")];
let line = line!["Name: ".bold(), "Remy".italic()];
let line = line!["bye"; 2];

The [text!] macro creates a Text that contains a sequence of Line. It is similar to the [vec!] macro. Each element is converted to a Line using [Into::into].

let name = "world!";
let text = text!["hello", format!("{name}")];
let text = text!["bye"; 2];
let name = "Bye!!!";
let text = text![line!["hello", "world".bold()], span!(Modifier::BOLD; "{name}")];

Layout Macros

If you are new to Ratatui, check out the Layout concepts article on the Ratatui website before proceeding.

The [constraints!] macro defines an array of Constraints:

let layout = Layout::horizontal(constraints![==50, ==30%, >=3, <=1, ==1/2, *=1]);

The [constraint!] macro defines individual Constraints:

let layout = Layout::horizontal([constraint!(==50)]);

The [vertical!] and [horizontal!] macros are a shortcut to defining a Layout:

let [top, main, bottom] = vertical![==1, *=1, >=3].areas(area);
let [left, main, right] = horizontal![>=20, *=1, >=20].areas(main);

Table Macros

The [row!] macro creates a Row for a Table that contains a sequence of Cells. It is similar to the [vec!] macro.

let rows = [
    row!["hello", "world"],
    row!["goodbye", "world"],
    row![
        text!["line 1", line!["Line", "2".bold()]],
        span!(Modifier::BOLD; "Cell 2"),
    ],
];
let table = Table::new(rows, constraints![==20, *=1]);

Contributing

Contributions to ratatui-macros are welcome! Whether it's submitting a bug report, a feature request, or a pull request, all forms of contributions are valued and appreciated.