ratatui/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.

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.

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::{constraints, vertical, horizontal};

Use the constraints! macro to define layout constraints:

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

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),
    ]
)

You can also 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 vertical_layout = vertical![==100%, >=3];
let [main, bottom] = vertical_layout.split(area).to_vec().try_into().unwrap();
assert_eq!(bottom.height, 3);

let horizontal_layout = horizontal![==100%, >=3];
let [main, right] = horizontal_layout.split(area).to_vec().try_into().unwrap();
assert_eq!(right.width, 3);

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.