Struct Rect 

pub struct Rect {
    pub x: u16,
    pub y: u16,
    pub width: u16,
    pub height: u16,
}

A rectangular area in the terminal.

A Rect represents a rectangular region in the terminal coordinate system, defined by its top-left corner position and dimensions. This is the fundamental building block for all layout operations and widget rendering in Ratatui.

Rectangles are used throughout the layout system to define areas where widgets can be rendered. They are typically created by Layout operations that divide terminal space, but can also be manually constructed for specific positioning needs.

The coordinate system uses the top-left corner as the origin (0, 0), with x increasing to the right and y increasing downward. All measurements are in character cells.

Construction and Conversion

• new - Create a new rectangle from coordinates and dimensions
• as_position - Convert to a position at the top-left corner
• as_size - Convert to a size representing the dimensions
• from((Position, Size)) - Create from (Position, Size) tuple
• from(((u16, u16), (u16, u16))) - Create from ((u16, u16), (u16, u16)) coordinate and dimension tuples
• [into((Position, Size))] - Convert to (Position, Size) tuple
• default - Create a zero-sized rectangle at origin

Geometry and Properties

• area - Calculate the total area in character cells
• is_empty - Check if the rectangle has zero area
• left, right, top, bottom - Get edge coordinates

Spatial Operations

• inner, outer - Apply margins to shrink or expand
• offset - Move the rectangle by a relative amount
• resize - Change the rectangle size while keeping the bottom/right in range
• union - Combine with another rectangle to create a bounding box
• intersection - Find the overlapping area with another rectangle
• clamp - Constrain the rectangle to fit within another

Positioning and Centering

• centered_horizontally - Center horizontally within a constraint
• centered_vertically - Center vertically within a constraint
• centered - Center both horizontally and vertically

Testing and Iteration

• contains - Check if a position is within the rectangle
• intersects - Check if it overlaps with another rectangle
• rows - Iterate over horizontal rows within the rectangle
• columns - Iterate over vertical columns within the rectangle
• positions - Iterate over all positions within the rectangle

Examples

To create a new Rect, use Rect::new. The size of the Rect will be clamped to keep the right and bottom coordinates within u16. Note that this clamping does not occur when creating a Rect directly.

use ratatui_core::layout::Rect;

let rect = Rect::new(1, 2, 3, 4);
assert_eq!(
    rect,
    Rect {
        x: 1,
        y: 2,
        width: 3,
        height: 4
    }
);

You can also create a Rect from a Position and a Size.

use ratatui_core::layout::{Position, Rect, Size};

let position = Position::new(1, 2);
let size = Size::new(3, 4);
let rect = Rect::from((position, size));
assert_eq!(
    rect,
    Rect {
        x: 1,
        y: 2,
        width: 3,
        height: 4
    }
);

To move a Rect without modifying its size, add or subtract an Offset to it.

use ratatui_core::layout::{Offset, Rect};

let rect = Rect::new(1, 2, 3, 4);
let offset = Offset::new(5, 6);
let moved_rect = rect + offset;
assert_eq!(moved_rect, Rect::new(6, 8, 3, 4));

To resize a Rect while ensuring it stays within bounds, use Rect::resize. The size is clamped so that right() and bottom() do not exceed u16::MAX.

use ratatui_core::layout::{Rect, Size};

let rect = Rect::new(u16::MAX - 1, u16::MAX - 1, 1, 1).resize(Size::new(10, 10));
assert_eq!(rect, Rect::new(u16::MAX - 1, u16::MAX - 1, 1, 1));

For comprehensive layout documentation and examples, see the layout module.

Fields

x: u16

The x coordinate of the top left corner of the Rect.

y: u16

The y coordinate of the top left corner of the Rect.

width: u16

The width of the Rect.

height: u16

The height of the Rect.

Implementations

impl Rect

pub const ZERO: Rect

A zero sized Rect at position 0,0

pub const MIN: Rect = Self::ZERO

The minimum possible Rect

pub const MAX: Rect

The maximum possible Rect

pub const fn new(x: u16, y: u16, width: u16, height: u16) -> Rect

Creates a new Rect, with width and height limited to keep both bounds within u16.

If the width or height would cause the right or bottom coordinate to be larger than the maximum value of u16, the width or height will be clamped to keep the right or bottom coordinate within u16.

Examples

use ratatui_core::layout::Rect;

let rect = Rect::new(1, 2, 3, 4);

pub const fn area(self) -> u32

The area of the Rect.

pub const fn is_empty(self) -> bool

Returns true if the Rect has no area.

pub const fn left(self) -> u16

Returns the left coordinate of the Rect.

pub const fn right(self) -> u16

Returns the right coordinate of the Rect. This is the first coordinate outside of the Rect.

If the right coordinate is larger than the maximum value of u16, it will be clamped to u16::MAX.

pub const fn top(self) -> u16

Returns the top coordinate of the Rect.

pub const fn bottom(self) -> u16

Returns the bottom coordinate of the Rect. This is the first coordinate outside of the Rect.

If the bottom coordinate is larger than the maximum value of u16, it will be clamped to u16::MAX.

pub const fn inner(self, margin: Margin) -> Rect

Returns a new Rect inside the current one, with the given margin on each side.

If the margin is larger than the Rect, the returned Rect will have no area.

pub const fn outer(self, margin: Margin) -> Rect

Returns a new Rect outside the current one, with the given margin applied on each side.

If the margin causes the Rect’s bounds to be outside the range of a u16, the Rect will be truncated to keep the bounds within u16. This will cause the size of the Rect to change.

The generated Rect may not fit inside the buffer or containing area, so it consider constraining the resulting Rect with Rect::clamp before using it.

pub fn offset(self, offset: Offset) -> Rect

Moves the Rect without modifying its size.

Moves the Rect according to the given offset without modifying its width or height.

• Positive x moves the whole Rect to the right, negative to the left.
• Positive y moves the whole Rect to the bottom, negative to the top.

See Offset for details.

pub const fn resize(self, size: Size) -> Rect

Resizes the Rect, clamping to keep the right and bottom within u16::MAX.

The position is preserved. If the requested size would push the Rect beyond the bounds of u16, the width or height is reduced so that right and bottom remain within range.

pub fn union(self, other: Rect) -> Rect

Returns a new Rect that contains both the current one and the given one.

pub fn intersection(self, other: Rect) -> Rect

Returns a new Rect that is the intersection of the current one and the given one.

If the two Rects do not intersect, the returned Rect will have no area.

pub const fn intersects(self, other: Rect) -> bool

Returns true if the two Rects intersect.

pub const fn contains(self, position: Position) -> bool

Returns true if the given position is inside the Rect.

The position is considered inside the Rect if it is on the Rect’s border.

Examples

use ratatui_core::layout::{Position, Rect};

let rect = Rect::new(1, 2, 3, 4);
assert!(rect.contains(Position { x: 1, y: 2 }));

pub fn clamp(self, other: Rect) -> Rect

Clamp this Rect to fit inside the other Rect.

If the width or height of this Rect is larger than the other Rect, it will be clamped to the other Rect’s width or height.

If the left or top coordinate of this Rect is smaller than the other Rect, it will be clamped to the other Rect’s left or top coordinate.

If the right or bottom coordinate of this Rect is larger than the other Rect, it will be clamped to the other Rect’s right or bottom coordinate.

This is different from Rect::intersection because it will move this Rect to fit inside the other Rect, while Rect::intersection instead would keep this Rect’s position and truncate its size to only that which is inside the other Rect.

Examples

use ratatui_core::layout::Rect;

let area = Rect::new(0, 0, 100, 100);
let rect = Rect::new(80, 80, 30, 30).clamp(area);
assert_eq!(rect, Rect::new(70, 70, 30, 30));

pub const fn rows(self) -> Rows

An iterator over rows within the Rect.

Each row is a full Rect region with height 1 that can be used for rendering widgets or as input to further layout methods.

Example

use ratatui_core::buffer::Buffer;
use ratatui_core::layout::{Constraint, Layout, Rect};
use ratatui_core::widgets::Widget;

fn render_list(area: Rect, buf: &mut Buffer) {
    // Renders "Item 0", "Item 1", etc. in each row
    for (i, row) in area.rows().enumerate() {
        format!("Item {i}").render(row, buf);
    }
}

fn render_with_nested_layout(area: Rect, buf: &mut Buffer) {
    // Splits each row into left/right areas and renders labels and content
    for (i, row) in area.rows().take(3).enumerate() {
        let [left, right] =
            Layout::horizontal([Constraint::Percentage(30), Constraint::Fill(1)]).areas(row);

        format!("{i}:").render(left, buf);
        "Content".render(right, buf);
    }
}

pub const fn columns(self) -> Columns

An iterator over columns within the Rect.

Each column is a full Rect region with width 1 that can be used for rendering widgets or as input to further layout methods.

Example

use ratatui_core::buffer::Buffer;
use ratatui_core::layout::Rect;
use ratatui_core::widgets::Widget;

fn render_columns(area: Rect, buf: &mut Buffer) {
    // Renders column indices (0-9 repeating) in each column
    for (i, column) in area.columns().enumerate() {
        format!("{}", i % 10).render(column, buf);
    }
}

pub const fn positions(self) -> Positions

An iterator over the positions within the Rect.

The positions are returned in a row-major order (left-to-right, top-to-bottom). Each position is a Position that represents a single cell coordinate.

Example

use ratatui_core::buffer::Buffer;
use ratatui_core::layout::{Position, Rect};
use ratatui_core::widgets::Widget;

fn render_positions(area: Rect, buf: &mut Buffer) {
    // Renders position indices (0-9 repeating) at each cell position
    for (i, position) in area.positions().enumerate() {
        buf[position].set_symbol(&format!("{}", i % 10));
    }
}

pub const fn as_position(self) -> Position

Returns a Position with the same coordinates as this Rect.

Examples

use ratatui_core::layout::Rect;

let rect = Rect::new(1, 2, 3, 4);
let position = rect.as_position();

pub const fn as_size(self) -> Size

Converts the Rect into a size struct.

pub fn centered_horizontally(self, constraint: Constraint) -> Rect

Returns a new Rect, centered horizontally based on the provided constraint.

Examples

use ratatui_core::layout::Constraint;
use ratatui_core::terminal::Frame;

fn render(frame: &mut Frame) {
    let area = frame.area().centered_horizontally(Constraint::Ratio(1, 2));
}

pub fn centered_vertically(self, constraint: Constraint) -> Rect

Returns a new Rect, centered vertically based on the provided constraint.

Examples

use ratatui_core::layout::Constraint;
use ratatui_core::terminal::Frame;

fn render(frame: &mut Frame) {
    let area = frame.area().centered_vertically(Constraint::Ratio(1, 2));
}

pub fn centered( self, horizontal_constraint: Constraint, vertical_constraint: Constraint, ) -> Rect

Returns a new Rect, centered horizontally and vertically based on the provided constraints.

Examples

use ratatui_core::layout::Constraint;
use ratatui_core::terminal::Frame;

fn render(frame: &mut Frame) {
    let area = frame
        .area()
        .centered(Constraint::Ratio(1, 2), Constraint::Ratio(1, 3));
}

pub fn layout<const N: usize>(self, layout: &Layout) -> [Rect; N]

Split the rect into a number of sub-rects according to the given Layout.

An ergonomic wrapper around Layout::split that returns an array of Rects instead of Rc<[Rect]>.

This method requires the number of constraints to be known at compile time. If you don’t know the number of constraints at compile time, use Layout::split instead.

Panics

Panics if the number of constraints is not equal to the length of the returned array.

Examples

use ratatui_core::layout::{Constraint, Layout, Rect};

let area = Rect::new(0, 0, 10, 10);
let layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
let [top, main] = area.layout(&layout);
assert_eq!(top, Rect::new(0, 0, 10, 1));
assert_eq!(main, Rect::new(0, 1, 10, 9));

// or explicitly specify the number of constraints:
let areas = area.layout::<2>(&layout);
assert_eq!(areas, [Rect::new(0, 0, 10, 1), Rect::new(0, 1, 10, 9),]);

pub fn layout_vec(self, layout: &Layout) -> Vec<Rect>

Split the rect into a number of sub-rects according to the given Layout.

An ergonomic wrapper around Layout::split that returns a Vec of Rects instead of Rc<[Rect]>.

Examples

use ratatui_core::layout::{Constraint, Layout, Rect};

let area = Rect::new(0, 0, 10, 10);
let layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
let areas = area.layout_vec(&layout);
assert_eq!(areas, vec![Rect::new(0, 0, 10, 1), Rect::new(0, 1, 10, 9),]);

pub fn try_layout<const N: usize>( self, layout: &Layout, ) -> Result<[Rect; N], TryFromSliceError>

Try to split the rect into a number of sub-rects according to the given Layout.

An ergonomic wrapper around Layout::split that returns an array of Rects instead of Rc<[Rect]>.

Errors

Returns an error if the number of constraints is not equal to the length of the returned array.

Examples

use ratatui_core::layout::{Constraint, Layout, Rect};

let area = Rect::new(0, 0, 10, 10);
let layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
let [top, main] = area.try_layout(&layout)?;
assert_eq!(top, Rect::new(0, 0, 10, 1));
assert_eq!(main, Rect::new(0, 1, 10, 9));

// or explicitly specify the number of constraints:
let areas = area.try_layout::<2>(&layout)?;
assert_eq!(areas, [Rect::new(0, 0, 10, 1), Rect::new(0, 1, 10, 9),]);

Trait Implementations

impl Add<Offset> for Rect

fn add(self, offset: Offset) -> Rect

Moves the rect by an offset without changing its size.

If the offset would move the any of the rect’s edges outside the bounds of u16, the rect’s position is clamped to the nearest edge.

type Output = Rect

The resulting type after applying the + operator.

impl AddAssign<Offset> for Rect

fn add_assign(&mut self, offset: Offset)

Moves the rect by an offset in place without changing its size.

If the offset would move the any of the rect’s edges outside the bounds of u16, the rect’s position is clamped to the nearest edge.

impl Clone for Rect

fn clone(&self) -> Rect

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Rect

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Rect

fn default() -> Rect

Returns the “default value” for a type.

impl Display for Rect

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<(Position, Size)> for Rect

fn from(_: (Position, Size)) -> Rect

Converts to this type from the input type.

impl From<Size> for Rect

fn from(size: Size) -> Rect

Creates a new Rect with the given size at Position::ORIGIN (0, 0).

impl Hash for Rect

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Rect

fn eq(&self, other: &Rect) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Sub<Offset> for Rect

fn sub(self, offset: Offset) -> Rect

Subtracts an offset from the rect without changing its size.

If the offset would move the any of the rect’s edges outside the bounds of u16, the rect’s position is clamped to the nearest

type Output = Rect

The resulting type after applying the - operator.

impl SubAssign<Offset> for Rect

fn sub_assign(&mut self, offset: Offset)

Moves the rect by an offset in place without changing its size.

If the offset would move the any of the rect’s edges outside the bounds of u16, the rect’s position is clamped to the nearest edge.

impl Copy for Rect

impl Eq for Rect

impl StructuralPartialEq for Rect