Ratatui Knowledge Patch

Ratatui knowledge patch

Reference index

Breaking changes and deprecations

Toolchain and crates

• Ratatui 0.30.0 requires Rust 1.86.0 and Rust 2024. The current 0.31.0 workspace requires Rust 1.88.0.
• Applications may keep using ratatui. Libraries can use ratatui-core, ratatui-widgets, and backend-specific crates for narrower dependencies.
• A no_std build disables defaults. Add layout-cache when a std build disables defaults but still needs cached layout, and add portable-atomic only on targets without native atomics.
• palette and serde require std.

Imports and renamed APIs

// 0.30.0+
use ratatui::layout::HorizontalAlignment;
use ratatui::widgets::{BlockExt, TitlePosition};

• Layout Alignment is now HorizontalAlignment.
• widgets::block and widgets::block::Title were removed. Pass content convertible to Line into Block::title; use title_top/title_bottom.
• The prelude includes Position and Size, but not Styled, Marker, CompletedFrame, TerminalOptions, or Viewport.

Style migration

const PANEL: Style = Style::new().blue().on_black();
let reset = Style::reset();

• Stylize methods are inherent on Style; Style itself no longer implements Styled.
• Replace style.reset() with the associated function Style::reset().
• Styling an owned String consumes it and produces Span<'static>; clone it first if it is still needed.

Backends

Custom backends must define Backend::Error and implement clear_region. Generic terminal helpers should return Result<T, B::Error> rather than assuming std::io::Error; TestBackend uses Infallible.

Generic backend conversions were replaced by explicit traits:

let color = Color::from_crossterm(value);
let backend_color = color.into_crossterm();

Equivalent FromTermion/IntoTermion and FromTermwiz/IntoTermwiz traits are available. Prefer ratatui::crossterm imports so the version matches the enabled backend feature.

Widget and buffer APIs

• Implement Widget for &Foo instead of relying on a direct WidgetRef for Foo implementation to gain Widget.
• StatefulWidget::State and StatefulWidgetRef::State may be unsized.
• Cell::symbol is Option<CompactString>; direct access must handle None.
• symbols::Marker is non-exhaustive. Add a wildcard match arm.
• Marker::Block is now a full block; use Marker::Bar for the former upper-half-block canvas appearance.
• Rect::area() returns u32, and its Positions fields are private.
• LineGauge::line_set is deprecated; set filled_symbol and unfilled_symbol separately.

Inference traps

Avoid unnecessary .into() when an API itself accepts Into:

let bar = Bar::default().label("name").text_value("42");
let tabs = Tabs::new(["A", "B"]).select(None);

Explicit conversions may be needed around Line: From<Cow<str>>, while Tabs::select(selected.into()) may need an explicitly typed option or selected as usize.

High-value layout APIs

Typed areas

let layout = Layout::vertical([Constraint::Length(3), Constraint::Min(0)]);
let [header, body] = area.layout(&layout);

Use Rect::try_layout or Layout::try_areas for fallible arrays, and Rect::layout_vec for a vector. Center areas with Rect::centered, centered_vertically, or centered_horizontally; expand with Rect::outer.

Fill, flex, and overlap

• Constraint::Fill(weight) proportionally divides excess space.
• Conflict priority is Min > Max > Length > Percentage > Ratio > Fill.
• Flex::SpaceAround now has CSS semantics; Flex::SpaceEvenly preserves the earlier equal-edge-gap behavior.
• Layout::split_with_spacers exposes generated spacer rectangles.
• Negative spacing creates overlaps. Later rendering wins shared cells:

let panes = Layout::horizontal(constraints).spacing(-1).split(area);

High-value terminal APIs

Lifecycle

For the default Crossterm terminal, prefer managed execution:

ratatui::run(|terminal| {
    terminal.draw(|frame| frame.render_widget("Hello", frame.area()))?;
    Ok(())
})

For manual control, call init, preserve the application result, call restore, and then return the result. Use try_init, try_init_with_options, and try_restore to propagate lifecycle errors.

Viewports and fallible drawing

• draw tracks backend resizing for fullscreen and inline viewports, but a fixed viewport stays at its configured Rect.
• Explicit Terminal::resize changes fixed viewports.
• Terminal::clear uses the latest resized area.
• Terminal::try_draw accepts a fallible callback; errors prevent the update.
• get_cursor_position/set_cursor_position replace untyped cursor methods.
• Terminal::size() returns the real backend Size, not a viewport Rect.

High-value widget APIs

Tables

state.select_column(Some(column));
state.select_cell(Some((row, column)));

Use column_highlight_style and cell_highlight_style. Overlapping selection styles apply as row, then column, then cell. Table can be collected from rows, and Table::flex controls unused column width.

Scrollbars, lists, and tabs

• Initialize a scrollbar with ScrollbarState::new(total) or it renders blank; then set position and optionally viewport_content_length.
• Set scrollbar orientation before custom symbols, because orientation resets the symbol set.
• List selection beyond the item count clamps to the last item.
• Tabs::select(None) renders no selected tab. The default selected style is reversed.

Optional and stateful rendering

Option<W>: Widget, so None draws nothing:

frame.render_widget(show.then(|| Paragraph::new("Details")), area);

Stateful widgets mutate separate persistent state during full-frame redraws. Keep child widget state inside the parent state and pass mutable model access when rendering can adjust offsets. For lightweight in-place mutation, implement Widget for &mut MyWidget.

Charts and canvas

• BarChart::grouped builds multiple labeled bar groups, and Bar implements Styled.
• Canvas adds Quadrant (2×2), Sextant (2×3), and Octant (2×4) markers.
• Canvas coordinates round to the nearest grid cell; out-of-bounds line starts are clipped, and Painter::bounds() exposes the current bounds.
• Overlaid charts and text preserve Braille and block marks for composition.
• Canvas grids may exceed 65,535 pseudo-pixels.

Text and color reminders

• Text += other appends lines but ignores the appended text's top-level style and alignment; line/span attributes remain.
• Text, Line, and Span implement UnicodeWidthStr with width and width_cjk; Span suppresses Unicode control characters.
• Styles patch in widget → text → line → span order.
• Color::from_hsl takes one palette::Hsl with saturation/lightness in 0.0..=1.0; Color::from_hsluv is also available with palette.
• ratatui::style::palette::tailwind supplies compile-time color families.

Testing reminders

• Snapshot a fixed-size TestBackend with insta and review changes with cargo insta review.
• Clip a custom widget's area with area.intersection(buf.area) before direct buffer writes.
• Expect snapshot changes from concise text/style Debug, nearest-cell canvas rounding, padded line-gauge labels, and inherited-alignment truncation.