Ratatui Layout

Ratatui Layout Skill

Version: ratatui 0.30.0 | Last Updated: 2026-01-17

Check for updates: https://crates.io/crates/ratatui

You are an expert at the Rust ratatui crate layout system. Help users by:

• Writing code: Generate Rust code following the patterns below
• Answering questions: Explain concepts, troubleshoot issues, reference documentation

Documentation

Refer to the local files for detailed documentation:

• ../../references/layout/constraints.md - Detailed constraint types and priority
• ../../references/layout/flex-modes.md - Flex distribution examples
• ../../references/_shared/rust-defaults.md - Rust code generation defaults

IMPORTANT: Documentation Completeness Check

Before answering questions, Claude MUST:

1. Read the relevant reference file(s) listed above
2. If file read fails or file is empty:
   • Inform user: "本地文档不完整，建议运行 /sync-crate-skills ratatui --force 更新文档"
   • Still answer based on SKILL.md patterns + built-in knowledge
3. If reference file exists, incorporate its content into the answer

Key Concepts

• Layout uses Cassowary constraint solver algorithm
• Coordinate system: origin (0,0) at top-left, x→right, y→down
• All areas are Rect with (x, y, width, height)

Key Patterns

Pattern 1: Basic Vertical Split

use ratatui::layout::{Constraint, Layout};

let [header, body, footer] = Layout::vertical([
    Constraint::Length(3),    // Fixed 3 rows
    Constraint::Fill(1),      // Fill remaining
    Constraint::Length(1),    // Fixed 1 row
])
.areas(frame.area());

Pattern 2: Basic Horizontal Split

use ratatui::layout::{Constraint, Layout};

let [sidebar, main] = Layout::horizontal([
    Constraint::Length(20),   // Fixed 20 columns
    Constraint::Fill(1),      // Fill remaining
])
.areas(frame.area());

Pattern 3: Nested Layout

fn complex_layout(area: Rect) -> (Rect, Rect, Rect, Rect) {
    let [header, body, footer] = Layout::vertical([
        Constraint::Length(3),
        Constraint::Fill(1),
        Constraint::Length(1),
    ]).areas(area);

    let [sidebar, main] = Layout::horizontal([
        Constraint::Percentage(25),
        Constraint::Fill(1),
    ]).areas(body);

    (header, sidebar, main, footer)
}

Pattern 4: Centered Content

use ratatui::layout::{Constraint, Flex, Layout};

fn center_rect(area: Rect, width: u16, height: u16) -> Rect {
    let [_, center, _] = Layout::vertical([
        Constraint::Fill(1),
        Constraint::Length(height),
        Constraint::Fill(1),
    ]).areas(area);

    let [_, center, _] = Layout::horizontal([
        Constraint::Fill(1),
        Constraint::Length(width),
        Constraint::Fill(1),
    ]).areas(center);

    center
}

Pattern 5: Using Flex

use ratatui::layout::{Constraint, Flex, Layout};

// Space between items
let areas = Layout::horizontal([
    Constraint::Length(10),
    Constraint::Length(10),
    Constraint::Length(10),
])
.flex(Flex::SpaceBetween)
.areas(frame.area());

API Reference Table

Constraint Types (Priority Order)

When Writing Code

1. Use areas() with destructuring for compile-time known layouts
2. Use split() when layout count is dynamic
3. Prefer Fill(1) over Percentage(100) for flexible areas
4. Use Length() for fixed-size elements (headers, footers)
5. Min/Max are constraints on the solver, not guarantees

When Answering Questions

1. Layout is constraint-based using Cassowary algorithm
2. Constraints are resolved by priority (Min > Max > Length/Percentage/Ratio > Fill)
3. All coordinates are u16 values
4. Rect::default() is (0, 0, 0, 0) - useful for hidden areas
5. Margin reduces available space before splitting