README.md

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

• Constraint-based Layouts: Easily define layout constraints such as fixed, percentage, minimum, and maximum sizes, as well as ratios.
• Directional Layouts: Specify layouts as either horizontal or vertical with simple macro commands.
• Span and Line macros: Make it easier to create spans and lines with styling.

Getting Started

To use ratatui-macros in your Rust project, add it 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,
    vertical,
    span,
    line,
};

Layout

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

Use the constraints! macro to define layout constraints:

use ratatui::prelude::*;
use ratatui_macros::constraints;

assert_eq!(
    constraints![==50, ==30%, >=3, <=1, ==1/2, *=1],
    [
        Constraint::Length(50),
        Constraint::Percentage(30),
        Constraint::Min(3),
        Constraint::Max(1),
        Constraint::Ratio(1, 2),
        Constraint::Fill(1),
    ]
)

use ratatui::prelude::*;
use ratatui_macros::constraints;

assert_eq!(
    constraints![==1/4; 4],
    [
        Constraint::Ratio(1, 4),
        Constraint::Ratio(1, 4),
        Constraint::Ratio(1, 4),
        Constraint::Ratio(1, 4),
    ]
)

Use the constraint! macro to define individual constraints:

use ratatui::prelude::*;
use ratatui_macros::constraint;

assert_eq!(
    constraint!(==50),
    Constraint::Length(50),
)

Create vertical and horizontal layouts using the vertical! and horizontal! macros:

use ratatui::prelude::*;
use ratatui_macros::{vertical, horizontal};

let area = Rect { x: 0, y: 0, width: 10, height: 10 };

let [main, bottom] = vertical![==100%, >=3].areas(area);

assert_eq!(bottom.y, 7);
assert_eq!(bottom.height, 3);

let [left, main, right] = horizontal![>=3, ==100%, >=3].areas(area);

assert_eq!(left.width, 3);
assert_eq!(right.width, 3);

Spans

The span! macro create raw and styled Spans. They each take a format string and arguments. span! accepts as the first parameter any value that can be converted to a Style followed by a ; followed by the format string and arguments.

use ratatui::prelude::*;
use ratatui_macros::span;

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

Line

The line! macro creates a Line that contains a sequence of spans. It is similar to the vec! macro.

use ratatui::prelude::*;
use ratatui_macros::line;

let name = "world!";
let line = line!["hello", format!("{name}")];
let line = line!["bye"; 2];

Text

The text! macro creates a Text that contains a sequence of lines. It is similar to the vec! macro.

use ratatui::prelude::*;
use ratatui_macros::{span, line, text};

let name = "world!";
let text = text!["hello", format!("{name}")];
let text = text!["bye"; 2];

It is even possible to use span! and line! in the text! macro:

use ratatui::prelude::*;
use ratatui_macros::{span, line, text};
let name = "Bye!!!";
let text = text![line!["hello", "world".bold()], span!(Modifier::BOLD; "{name}")];

Row

The row! macro creates a Row that contains a sequence of Cell. It is similar to the vec! macro. A Row represents a sequence of Cells in a single row of a table.

use ratatui::prelude::*;
use ratatui_macros::row;

let rows = [
    row!["hello", "world"],
    row!["goodbye", "world"],
];

It is even possible to use span!, line! and text! in the row! macro:

use ratatui::prelude::*;
use ratatui_macros::{span, line, text, row};
let name = "Bye!!!";
let text = row![text![line!["hello", "world".bold()]], span!(Modifier::BOLD; "{name}")];

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.