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.
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,
};
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);
The span!
macro create raw and styled Span
s. 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}");
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];
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}")];
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 Cell
s 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}")];
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.