Ratatui Knowledge Patch

Covers new APIs and breaking changes in Ratatui 0.30-0.31. Assumes familiarity with Ratatui basics through 0.29.x (tui-rs heritage, widget system, immediate-mode rendering).

Topic	File	Key Content
Layout	references/layout.md	Rect arithmetic, Flex::SpaceEvenly, centered variants
Widgets	references/widgets.md	BarChart, List, canvas markers, LineGauge, ScrollbarState
Styling & Borders	references/styling-and-borders.md	Border merging, dashed borders, Color conversions
Migration Guide	references/migration-guide.md	Alignment rename, WidgetRef reversal, backend Error type, FromCrossterm
Backend & Platform	references/backend-and-platform.md	Crossterm versions, no_std, ratatui-core modularization

Entry Point: ratatui::run()

Added in 0.30. Handles init()/restore() automatically. Accepts a closure that receives &mut DefaultTerminal.

fn main() -> Result<(), Box<dyn std::error::Error>> {
    ratatui::run(|terminal| {
        loop {
            terminal.draw(|frame| frame.render_widget("Hello World!", frame.area()))?;
            if crossterm::event::read()?.is_key_press() {
                break Ok(());
            }
        }
    })
}
// Also works with methods: ratatui::run(App::new().run)?;

Rect Layout Methods

Added in 0.30. Rect::layout splits into a fixed-size array with compile-time size inference. Rect::centered centers a sub-rect using constraints.

let layout = Layout::vertical([Constraint::Fill(1); 2]);
let [top, main] = area.layout(&layout); // array size inferred
// Fallible: area.try_layout(&layout)?, layout.try_areas(area)?
// Vec: area.layout_vec(&layout)

let popup = area.centered(Constraint::Ratio(1, 2), Constraint::Ratio(1, 3));
let strip = area.centered_vertically(Constraint::Length(5));
let col = area.centered_horizontally(Constraint::Length(20));

Rect Arithmetic

use ratatui::layout::Offset;

let moved = rect + Offset { x: 5, y: 0 }; // move right
let moved = rect - Offset { x: 5, y: 0 }; // move left
let expanded = rect.outer(Margin {
    horizontal: 2,
    vertical: 1,
}); // inverse of inner()
let resized = rect.resize(new_width, new_height);

See references/layout.md for Flex changes and Direction::perpendicular().

Style Const Shorthand

Added in 0.30. Color methods like .blue(), .on_black() are now const on Style directly (no longer require Styled trait).

const MY_STYLE: Style = Style::new().blue().on_black();

block::Title Removed

Breaking in 0.30. Use Line directly for block titles. block::Position moved to widgets::TitlePosition. BlockExt moved to widgets::BlockExt.

// Old: Block::default().title(Title::from("Hi").position(Position::Bottom))
// New:
Block::default().title_bottom(Line::from("Hi").centered());

Flex::SpaceAround Semantics Changed

Breaking in 0.30. Old SpaceAround behavior is now Flex::SpaceEvenly. New SpaceAround matches CSS flexbox semantics (inter-item spacing is 2x edge spacing).

Key Widget Changes (0.30)

BarChart constructors

let chart = BarChart::grouped(groups); // default vertical grouped
let chart = BarChart::horizontal(groups);
let bar = Bar::with_label("Sales", 42);
let group = BarGroup::with_label("Q1", bars);

List highlight symbol styling

List::highlight_symbol now accepts Into<Line>, enabling styled highlight symbols (no longer const-compatible):

List::new(items).highlight_symbol(Line::from(">>").red().bold())

New canvas markers

Marker::Quadrant (2x2), Marker::Sextant (2x3), Marker::Octant (2x4, like Braille but filled). Marker is now #[non_exhaustive].

Other widget additions

• ScrollbarState::get_position() retrieves current scroll position
• Tabs::width() calculates total width including dividers
• Text += Text via AddAssign
• LineGauge::filled_symbol / unfilled_symbol replace deprecated line_set

See references/widgets.md for full details and code examples.

Styling & Borders

Border merging

Added in 0.30. Overlapping borders auto-merge into clean intersections via MergeStrategy.

New dashed BorderTypes

LightDoubleDashed, HeavyDoubleDashed, LightTripleDashed, HeavyTripleDashed, LightQuadrupleDashed, HeavyQuadrupleDashed.

Color RGB conversions

let c = Color::from([255, 0, 0]); // from array
let c = Color::from((255, 0, 0)); // from tuple

Style::has_modifier() checks for a specific modifier.

See references/styling-and-borders.md for full details.

Migration Quick Reference (0.30 Breaking Changes)

Change	Migration
block::Title removed	Use Line directly; title_top() / title_bottom()
Alignment renamed	Now HorizontalAlignment (alias exists). VerticalAlignment added
Flex::SpaceAround changed	Old behavior is now Flex::SpaceEvenly
From impls for backend types removed	Use FromCrossterm/IntoCrossterm (and Termion/Termwiz equivalents)
Backend Error type required	Custom backends: add type Error; implement clear_region
WidgetRef reversed	Implement Widget for &Foo; use FrameExt for render_widget_ref()

See references/migration-guide.md for full migration details with code examples.

Version Notes

• 0.30.1: AsRef<Self> impls added for built-in widgets. May cause type inference ambiguity in rare cases -- add explicit type annotations if needed.
• 0.31: MSRV bumped to 1.88.0.

Reference Files

For detailed coverage of each topic area, consult:

• references/layout.md -- Rect arithmetic (+/- Offset, outer, resize), Flex changes, Size::area()
• references/widgets.md -- BarChart constructors, List highlight, canvas markers, LineGauge symbols, ScrollbarState, Tabs, Text AddAssign, AsRef impls
• references/styling-and-borders.md -- Border merging (MergeStrategy), all dashed border types, Color RGB conversions, Style::has_modifier
• references/migration-guide.md -- Complete migration details for all 0.30 breaking changes with before/after code
• references/backend-and-platform.md -- Multiple crossterm version support, no_std, ratatui-core for library authors