Struct Layout 

pub struct Layout { /* private fields */ }

The primary layout engine for dividing terminal space using constraints and direction.

A layout is a set of constraints that can be applied to a given area to split it into smaller rectangular areas. This is the core building block for creating structured user interfaces in terminal applications.

A layout is composed of:

• a direction (horizontal or vertical)
• a set of constraints (length, ratio, percentage, fill, min, max)
• a margin (horizontal and vertical), the space between the edge of the main area and the split areas
• a flex option that controls space distribution
• a spacing option that controls gaps between segments

The algorithm used to compute the layout is based on the kasuari solver, a linear constraint solver that computes positions and sizes to satisfy as many constraints as possible in order of their priorities.

When the layout is computed, the result is cached in a thread-local cache, so that subsequent calls with the same parameters are faster. The cache is a LruCache, and the size of the cache can be configured using Layout::init_cache() when the layout-cache feature is enabled.

Construction

• default - Create a layout with default values (vertical direction, no constraints, no margin)
• new - Create a new layout with a given direction and constraints
• vertical - Create a new vertical layout with the given constraints
• horizontal - Create a new horizontal layout with the given constraints

Configuration

• direction - Set the direction of the layout
• constraints - Set the constraints of the layout
• margin - Set uniform margin on all sides
• horizontal_margin - Set the horizontal margin of the layout
• vertical_margin - Set the vertical margin of the layout
• flex - Set the way space is distributed when constraints are satisfied
• spacing - Set the gap between the constraints of the layout

Layout Operations

• areas - Split area into fixed number of rectangles (compile-time known)
• spacers - Get spacer rectangles between layout areas
• split - Split area into rectangles (runtime determined count)
• split_with_spacers - Split area and return both areas and spacers

Cache Management

• init_cache - Initialize layout cache with custom size

Example

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

fn render(area: Rect, buf: &mut Buffer) {
    let layout = Layout::vertical([Constraint::Length(5), Constraint::Fill(1)]);
    let [top, bottom] = layout.areas(area);
    Text::from("foo").render(top, buf);
    Text::from("bar").render(bottom, buf);
}

See the layout, flex, and constraints examples in the Examples folder for more details about how to use layouts.

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

Implementations

impl Layout

pub const DEFAULT_CACHE_SIZE: usize = 500usize

Available on crate feature layout-cache only.

This is a somewhat arbitrary size for the layout cache based on adding the columns and rows on my laptop’s terminal (171+51 = 222) and doubling it for good measure and then adding a bit more to make it a round number. This gives enough entries to store a layout for every row and every column, twice over, which should be enough for most apps. For those that need more, the cache size can be set with Layout::init_cache() (requires the layout-cache feature).

pub fn new<I>(direction: Direction, constraints: I) -> Self

where I: IntoIterator, I::Item: Into<Constraint>,

Creates a new layout with default values.

The constraints parameter accepts any type that implements IntoIterator<Item = Into<Constraint>>. This includes arrays, slices, vectors, iterators. Into<Constraint> is implemented on u16, so you can pass an array, Vec, etc. of u16 to this function to create a layout with fixed size chunks.

Default values for the other fields are:

• margin: 0, 0
• flex: Flex::Start
• spacing: 0

Examples

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

Layout::new(
    Direction::Horizontal,
    [Constraint::Length(5), Constraint::Fill(1)],
);

Layout::new(
    Direction::Vertical,
    [1, 2, 3].iter().map(|&c| Constraint::Length(c)),
);

Layout::new(Direction::Horizontal, vec![1, 2]);

pub fn vertical<I>(constraints: I) -> Self

where I: IntoIterator, I::Item: Into<Constraint>,

Creates a new vertical layout with default values.

The constraints parameter accepts any type that implements IntoIterator<Item = Into<Constraint>>. This includes arrays, slices, vectors, iterators, etc.

Examples

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

let layout = Layout::vertical([Constraint::Length(5), Constraint::Fill(1)]);

pub fn horizontal<I>(constraints: I) -> Self

where I: IntoIterator, I::Item: Into<Constraint>,

Creates a new horizontal layout with default values.

The constraints parameter accepts any type that implements IntoIterator<Item = Into<Constraint>>. This includes arrays, slices, vectors, iterators, etc.

Examples

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

let layout = Layout::horizontal([Constraint::Length(5), Constraint::Fill(1)]);

pub fn init_cache(cache_size: NonZeroUsize)

Available on crate feature layout-cache only.

Initialize an empty cache with a custom size. The cache is keyed on the layout and area, so that subsequent calls with the same parameters are faster. The cache is a LruCache, and grows until cache_size is reached.

By default, the cache size is Self::DEFAULT_CACHE_SIZE.

pub const fn direction(self, direction: Direction) -> Self

Set the direction of the layout.

Examples

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

let layout = Layout::default()
    .direction(Direction::Horizontal)
    .constraints([Constraint::Length(5), Constraint::Fill(1)])
    .split(Rect::new(0, 0, 10, 10));
assert_eq!(layout[..], [Rect::new(0, 0, 5, 10), Rect::new(5, 0, 5, 10)]);

let layout = Layout::default()
    .direction(Direction::Vertical)
    .constraints([Constraint::Length(5), Constraint::Fill(1)])
    .split(Rect::new(0, 0, 10, 10));
assert_eq!(layout[..], [Rect::new(0, 0, 10, 5), Rect::new(0, 5, 10, 5)]);

pub fn constraints<I>(self, constraints: I) -> Self

where I: IntoIterator, I::Item: Into<Constraint>,

Sets the constraints of the layout.

The constraints parameter accepts any type that implements IntoIterator<Item = Into<Constraint>>. This includes arrays, slices, vectors, iterators. Into<Constraint> is implemented on u16, so you can pass an array or vec of u16 to this function to create a layout with fixed size chunks.

Note that the constraints are applied to the whole area that is to be split, so using percentages and ratios with the other constraints may not have the desired effect of splitting the area up. (e.g. splitting 100 into [min 20, 50%, 50%], may not result in [20, 40, 40] but rather an indeterminate result between [20, 50, 30] and [20, 30, 50]).

Examples

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

let layout = Layout::default()
    .constraints([
        Constraint::Percentage(20),
        Constraint::Ratio(1, 5),
        Constraint::Length(2),
        Constraint::Min(2),
        Constraint::Max(2),
    ])
    .split(Rect::new(0, 0, 10, 10));
assert_eq!(
    layout[..],
    [
        Rect::new(0, 0, 10, 2),
        Rect::new(0, 2, 10, 2),
        Rect::new(0, 4, 10, 2),
        Rect::new(0, 6, 10, 2),
        Rect::new(0, 8, 10, 2),
    ]
);

Layout::default().constraints([Constraint::Fill(1)]);
Layout::default().constraints(&[Constraint::Fill(1)]);
Layout::default().constraints(vec![Constraint::Fill(1)]);
Layout::default().constraints([Constraint::Fill(1)].iter().filter(|_| true));
Layout::default().constraints([1, 2, 3].iter().map(|&c| Constraint::Length(c)));
Layout::default().constraints([1, 2, 3]);
Layout::default().constraints(vec![1, 2, 3]);

pub const fn margin(self, margin: u16) -> Self

Set the margin of the layout.

Examples

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

let layout = Layout::default()
    .constraints([Constraint::Fill(1)])
    .margin(2)
    .split(Rect::new(0, 0, 10, 10));
assert_eq!(layout[..], [Rect::new(2, 2, 6, 6)]);

pub const fn horizontal_margin(self, horizontal: u16) -> Self

Set the horizontal margin of the layout.

Examples

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

let layout = Layout::default()
    .constraints([Constraint::Fill(1)])
    .horizontal_margin(2)
    .split(Rect::new(0, 0, 10, 10));
assert_eq!(layout[..], [Rect::new(2, 0, 6, 10)]);

pub const fn vertical_margin(self, vertical: u16) -> Self

Set the vertical margin of the layout.

Examples

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

let layout = Layout::default()
    .constraints([Constraint::Fill(1)])
    .vertical_margin(2)
    .split(Rect::new(0, 0, 10, 10));
assert_eq!(layout[..], [Rect::new(0, 2, 10, 6)]);

pub const fn flex(self, flex: Flex) -> Self

The flex method allows you to specify the flex behavior of the layout.

Arguments

• flex: A Flex enum value that represents the flex behavior of the layout. It can be one of the following:
  • Flex::Legacy: The last item is stretched to fill the excess space.
  • Flex::Start: The items are aligned to the start of the layout.
  • Flex::Center: The items are aligned to the center of the layout.
  • Flex::End: The items are aligned to the end of the layout.
  • Flex::SpaceBetween: The items are evenly distributed with equal space between them.
  • Flex::SpaceAround: The items are evenly distributed with equal space around them, except the first and last items, which have half the space on their sides.
  • Flex::SpaceEvenly: The items are evenly distributed with equal space around them.

Examples

In this example, the items in the layout will be aligned to the start.

use ratatui_core::layout::Constraint::*;
use ratatui_core::layout::{Flex, Layout};

let layout = Layout::horizontal([Length(20), Length(20), Length(20)]).flex(Flex::Start);

In this example, the items in the layout will be stretched equally to fill the available space.

use ratatui_core::layout::Constraint::*;
use ratatui_core::layout::{Flex, Layout};

let layout = Layout::horizontal([Length(20), Length(20), Length(20)]).flex(Flex::Legacy);

pub fn spacing<T>(self, spacing: T) -> Self

where T: Into<Spacing>,

Sets the spacing between items in the layout.

The spacing method sets the spacing between items in the layout. The spacing is applied evenly between all segments. The spacing value represents the number of cells between each item.

Spacing can be positive integers, representing gaps between segments; or negative integers representing overlaps. Additionally, one of the variants of the Spacing enum can be passed to this function. See the documentation of the Spacing enum for more information.

Note that if the layout has only one segment, the spacing will not be applied. Also, spacing will not be applied for Flex::SpaceAround, Flex::SpaceEvenly and Flex::SpaceBetween

Examples

In this example, the spacing between each item in the layout is set to 2 cells.

use ratatui_core::layout::Constraint::*;
use ratatui_core::layout::Layout;

let layout = Layout::horizontal([Length(20), Length(20), Length(20)]).spacing(2);

In this example, the spacing between each item in the layout is set to -1 cells, i.e. the three segments will have an overlapping border.

use ratatui_core::layout::Constraint::*;
use ratatui_core::layout::Layout;
let layout = Layout::horizontal([Length(20), Length(20), Length(20)]).spacing(-1);

pub fn areas<const N: usize>(&self, area: Rect) -> [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::Fill(1)]);
let [top, main] = layout.areas(area);

// or explicitly specify the number of constraints:
let areas = layout.areas::<2>(area);

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

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.

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] = layout.try_areas(area)?;

// or explicitly specify the number of constraints:
let areas = layout.try_areas::<2>(area)?;

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

Split the rect into a number of sub-rects according to the given Layout and return just the spacers between the areas.

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_with_spacers instead.

This method is similar to Layout::areas, and can be called with the same parameters, but it returns just the spacers between the areas. The result of calling the areas method is cached, so this will generally not re-run the solver, but will just return the cached result.

Panics

Panics if the number of constraints + 1 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::Fill(1)]);
let [top, main] = layout.areas(area);
let [before, inbetween, after] = layout.spacers(area);

// or explicitly specify the number of constraints:
let spacers = layout.spacers::<3>(area);

pub fn split(&self, area: Rect) -> Rc<[Rect]>

Wrapper function around the kasuari solver to be able to split a given area into smaller ones based on the preferred widths or heights and the direction.

Note that the constraints are applied to the whole area that is to be split, so using percentages and ratios with the other constraints may not have the desired effect of splitting the area up. (e.g. splitting 100 into [min 20, 50%, 50%], may not result in [20, 40, 40] but rather an indeterminate result between [20, 50, 30] and [20, 30, 50]).

This method stores the result of the computation in a thread-local cache keyed on the layout and area, so that subsequent calls with the same parameters are faster. The cache is a LruCache, and grows until Self::DEFAULT_CACHE_SIZE is reached by default. If the cache is initialized with Layout::init_cache(), it grows until the initialized cache size.

There is a helper method that can be used to split the whole area into smaller ones based on the layout: Layout::areas(). That method is a shortcut for calling this method. It allows you to destructure the result directly into variables, which is useful when you know at compile time the number of areas that will be created.

Examples

use ratatui_core::layout::{Constraint, Direction, Layout, Rect};
let layout = Layout::default()
    .direction(Direction::Vertical)
    .constraints([Constraint::Length(5), Constraint::Fill(1)])
    .split(Rect::new(2, 2, 10, 10));
assert_eq!(layout[..], [Rect::new(2, 2, 10, 5), Rect::new(2, 7, 10, 5)]);

let layout = Layout::default()
    .direction(Direction::Horizontal)
    .constraints([Constraint::Ratio(1, 3), Constraint::Ratio(2, 3)])
    .split(Rect::new(0, 0, 9, 2));
assert_eq!(layout[..], [Rect::new(0, 0, 3, 2), Rect::new(3, 0, 6, 2)]);

pub fn split_with_spacers(&self, area: Rect) -> (Rc<[Rect]>, Rc<[Rect]>)

Wrapper function around the kasuari solver that splits the given area into smaller ones based on the preferred widths or heights and the direction, with the ability to include spacers between the areas.

This method is similar to split, but it returns two sets of rectangles: one for the areas and one for the spacers.

This method stores the result of the computation in a thread-local cache keyed on the layout and area, so that subsequent calls with the same parameters are faster. The cache is a LruCache, and grows until Self::DEFAULT_CACHE_SIZE is reached by default. If the cache is initialized with Layout::init_cache(), it grows until the initialized cache size.

Examples

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

let (areas, spacers) = Layout::default()
    .direction(Direction::Vertical)
    .constraints([Constraint::Length(5), Constraint::Fill(1)])
    .split_with_spacers(Rect::new(2, 2, 10, 10));
assert_eq!(areas[..], [Rect::new(2, 2, 10, 5), Rect::new(2, 7, 10, 5)]);
assert_eq!(
    spacers[..],
    [
        Rect::new(2, 2, 10, 0),
        Rect::new(2, 7, 10, 0),
        Rect::new(2, 12, 10, 0)
    ]
);

let (areas, spacers) = Layout::default()
    .direction(Direction::Horizontal)
    .spacing(1)
    .constraints([Constraint::Ratio(1, 3), Constraint::Ratio(2, 3)])
    .split_with_spacers(Rect::new(0, 0, 10, 2));
assert_eq!(areas[..], [Rect::new(0, 0, 3, 2), Rect::new(4, 0, 6, 2)]);
assert_eq!(
    spacers[..],
    [
        Rect::new(0, 0, 0, 2),
        Rect::new(3, 0, 1, 2),
        Rect::new(10, 0, 0, 2)
    ]
);

Trait Implementations

impl Clone for Layout

fn clone(&self) -> Layout

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Layout

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

Formats the value using the given formatter.

impl Default for Layout

fn default() -> Layout

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Layout

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Hash for Layout

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

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 Layout

fn eq(&self, other: &Layout) -> 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 Serialize for Layout

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Layout

impl StructuralPartialEq for Layout