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.

Crate Organization

ratatui-macros is part of the Ratatui workspace that was modularized in version 0.30.0. This crate provides declarative macros to reduce boilerplate when working with Ratatui.

When to use ratatui-macros:

• You want to reduce boilerplate when creating styled text, layouts, or tables
• You prefer macro-based syntax for creating UI elements
• You need compile-time generation of repetitive UI code

When to use the main ratatui crate:

• Building applications (recommended - includes macros when the macros feature is enabled)
• You want the convenience of having everything available

For detailed information about the workspace organization, see ARCHITECTURE.md.