Crate 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.

Re-exports

pub use ratatui_core;

Macros

constraint

Creates a single constraint.

constraints

Creates an array of constraints.

horizontal

Creates a horizontal layout with specified constraints.

line

A macro for creating a Line using vec! syntax.

row

A macro for creating a Row using vec! syntax.

span

A macro for creating a Span using formatting syntax.

text

A macro for creating a Text using vec! syntax.

vertical

Creates a vertical layout with specified constraints.