Struct Block

pub struct Block<'a> { /* private fields */ }

Base widget to be used to display a box border around all upper level ones.

The borders can be configured with Block::borders and others. A block can have multiple Title using Block::title. It can also be styled and padded.

You can call the title methods multiple times to add multiple titles. Each title will be rendered with a single space separating titles that are in the same position or alignment. When both centered and non-centered titles are rendered, the centered space is calculated based on the full width of the block, rather than the leftover width.

Titles are not rendered in the corners of the block unless there is no border on that edge. If the block is too small and multiple titles overlap, the border may get cut off at a corner.

┌With at least a left border───

Without left border───

Constructor methods

• Block::new creates a new Block with no border or paddings.
• Block::bordered Create a new block with all borders shown.

Setter methods

These methods are fluent setters. They return a new Block with the specified property set.

• Block::borders Defines which borders to display.
• Block::border_style Defines the style of the borders.
• Block::border_type Sets the symbols used to display the border (e.g. single line, double line, thick or rounded borders).
• Block::padding Defines the padding inside a Block.
• Block::style Sets the base style of the widget.
• Block::title Adds a title to the block.
• Block::title_alignment Sets the default Alignment for all block titles.
• Block::title_style Applies the style to all titles.
• Block::title_top Adds a title to the top of the block.
• Block::title_bottom Adds a title to the bottom of the block.
• Block::title_position Adds a title to the block.

Other Methods

• Block::inner Compute the inner area of a block based on its border visibility rules.

Styles are applied first to the entire block, then to the borders, and finally to the titles. If the block is used as a container for another widget, the inner widget can also be styled. See Style for more information on how merging styles works.

Examples

use ratatui::{
    style::{Color, Style},
    widgets::{Block, BorderType, Borders},
};

Block::new()
    .border_type(BorderType::Rounded)
    .borders(Borders::LEFT | Borders::RIGHT)
    .border_style(Style::default().fg(Color::White))
    .style(Style::default().bg(Color::Black))
    .title("Block");

You may also use multiple titles like in the following:

use ratatui::widgets::{
    block::{Position, Title},
    Block,
};

Block::new()
    .title("Title 1")
    .title(Title::from("Title 2").position(Position::Bottom));

You can also pass it as parameters of another widget so that the block surrounds them:

use ratatui::widgets::{Block, Borders, List};

let surrounding_block = Block::default()
    .borders(Borders::ALL)
    .title("Here is a list of items");
let items = ["Item 1", "Item 2", "Item 3"];
let list = List::new(items).block(surrounding_block);

Implementations

impl<'a> Block<'a>

pub const fn new() -> Self

Creates a new block with no Borders or Padding.

pub const fn bordered() -> Self

Create a new block with all borders shown

use ratatui::widgets::{Block, Borders};

assert_eq!(Block::bordered(), Block::new().borders(Borders::ALL));

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

where T: Into<Title<'a>>,

Adds a title to the block.

The title function allows you to add a title to the block. You can call this function multiple times to add multiple titles.

Each title will be rendered with a single space separating titles that are in the same position or alignment. When both centered and non-centered titles are rendered, the centered space is calculated based on the full width of the block, rather than the leftover width.

You can provide any type that can be converted into Title including: strings, string slices (&str), borrowed strings (Cow<str>), spans, or vectors of spans (Vec<Span>).

By default, the titles will avoid being rendered in the corners of the block but will align against the left or right edge of the block if there is no border on that edge. The following demonstrates this behavior, notice the second title is one character off to the left.

┌With at least a left border───

Without left border───

Note: If the block is too small and multiple titles overlap, the border might get cut off at a corner.

Examples

See the Block example for a visual representation of how the various borders and styles look when rendered.

The following example demonstrates:

• Default title alignment
• Multiple titles (notice “Center” is centered according to the full with of the block, not the leftover space)
• Two titles with the same alignment (notice the left titles are separated)

use ratatui::{
    text::Line,
    widgets::{Block, Borders},
};

Block::new()
    .title("Title") // By default in the top left corner
    .title(Line::from("Left").left_aligned()) // also on the left
    .title(Line::from("Right").right_aligned())
    .title(Line::from("Center").centered());
// Renders
// ┌Title─Left────Center─────────Right┐

See also

Titles attached to a block can have default behaviors. See

• Block::title_style
• Block::title_alignment
• Block::title_position

Future improvements

In a future release of Ratatui this method will be changed to accept Into<Line> instead of Into<Title>. This allows us to remove the unnecessary Title struct and store the position in the block itself. For more information see https://github.com/ratatui/ratatui/issues/738.

pub fn title_top<T: Into<Line<'a>>>(self, title: T) -> Self

Adds a title to the top of the block.

You can provide any type that can be converted into Line including: strings, string slices (&str), borrowed strings (Cow<str>), spans, or vectors of spans (Vec<Span>).

Example

use ratatui::{ widgets::Block, text::Line };

Block::bordered()
    .title_top("Left1") // By default in the top left corner
    .title_top(Line::from("Left2").left_aligned())
    .title_top(Line::from("Right").right_aligned())
    .title_top(Line::from("Center").centered());

// Renders
// ┌Left1─Left2───Center─────────Right┐
// │                                  │
// └──────────────────────────────────┘

pub fn title_bottom<T: Into<Line<'a>>>(self, title: T) -> Self

Adds a title to the bottom of the block.

You can provide any type that can be converted into Line including: strings, string slices (&str), borrowed strings (Cow<str>), spans, or vectors of spans (Vec<Span>).

Example

use ratatui::{ widgets::Block, text::Line };

Block::bordered()
    .title_bottom("Left1") // By default in the top left corner
    .title_bottom(Line::from("Left2").left_aligned())
    .title_bottom(Line::from("Right").right_aligned())
    .title_bottom(Line::from("Center").centered());

// Renders
// ┌──────────────────────────────────┐
// │                                  │
// └Left1─Left2───Center─────────Right┘

pub fn title_style<S: Into<Style>>(self, style: S) -> Self

Applies the style to all titles.

This style will be applied to all titles of the block. If a title has a style set, it will be applied after this style. This style will be applied after any Block::style or Block::border_style is applied.

See Style for more information on how merging styles works.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

pub const fn title_alignment(self, alignment: Alignment) -> Self

Sets the default Alignment for all block titles.

Titles that explicitly set an Alignment will ignore this.

Example

This example aligns all titles in the center except the “right” title which explicitly sets Alignment::Right.

use ratatui::{layout::Alignment, text::Line, widgets::Block};

Block::new()
    .title_alignment(Alignment::Center)
    // This title won't be aligned in the center
    .title(Line::from("right").right_aligned())
    .title("foo")
    .title("bar");

pub const fn title_position(self, position: Position) -> Self

Sets the default Position for all block titles.

Titles that explicitly set a Position will ignore this.

Example

This example positions all titles on the bottom except the “top” title which explicitly sets Position::Top.

use ratatui::widgets::{block::Position, Block};

Block::new()
    .title_position(Position::Bottom)
    // This title won't be aligned in the center
    .title_top("top")
    .title("foo")
    .title("bar");

pub fn border_style<S: Into<Style>>(self, style: S) -> Self

Defines the style of the borders.

This style is applied only to the areas covered by borders, and is applied to the block after any Block::style is applied.

See Style for more information on how merging styles works.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

Example

This example shows a Block with blue borders.

use ratatui::{
    style::{Style, Stylize},
    widgets::Block,
};
Block::bordered().border_style(Style::new().blue());

pub fn style<S: Into<Style>>(self, style: S) -> Self

Defines the style of the entire block.

This is the most generic Style a block can receive, it will be merged with any other more specific styles. Elements can be styled further with Block::title_style and Block::border_style, which will be applied on top of this style. If the block is used as a container for another widget (e.g. a Paragraph), then the style of the widget is generally applied before this style.

See Style for more information on how merging styles works.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

Example

use ratatui::{
    style::{Color, Style, Stylize},
    widgets::{Block, Paragraph},
};

let block = Block::new().style(Style::new().red().on_black());

// For border and title you can additionally apply styles on top of the block level style.
let block = Block::new()
    .style(Style::new().red().bold().italic())
    .border_style(Style::new().not_italic()) // will be red and bold
    .title_style(Style::new().not_bold()) // will be red and italic
    .title("Title");

// To style the inner widget, you can style the widget itself.
let paragraph = Paragraph::new("Content")
    .block(block)
    .style(Style::new().white().not_bold()); // will be white, and italic

pub const fn borders(self, flag: Borders) -> Self

Defines which borders to display.

Borders can also be styled with Block::border_style and Block::border_type.

Examples

Display left and right borders.

use ratatui::widgets::{Block, Borders};
Block::new().borders(Borders::LEFT | Borders::RIGHT);

To show all borders you can abbreviate this with Block::bordered

pub const fn border_type(self, border_type: BorderType) -> Self

Sets the symbols used to display the border (e.g. single line, double line, thick or rounded borders).

Setting this overwrites any custom border_set that was set.

See BorderType for the full list of available symbols.

Examples

use ratatui::widgets::{Block, BorderType};
Block::bordered()
    .border_type(BorderType::Rounded)
    .title("Block");
// Renders
// ╭Block╮
// │     │
// ╰─────╯

pub const fn border_set(self, border_set: Set) -> Self

Sets the symbols used to display the border as a crate::symbols::border::Set.

Setting this overwrites any border_type that was set.

Examples

use ratatui::{widgets::Block, symbols};

Block::bordered().border_set(symbols::border::DOUBLE).title("Block");
// Renders
// ╔Block╗
// ║     ║
// ╚═════╝

pub const fn padding(self, padding: Padding) -> Self

Defines the padding inside a Block.

See Padding for more information.

Examples

This renders a Block with no padding (the default).

use ratatui::widgets::{Block, Padding};

Block::bordered().padding(Padding::ZERO);
// Renders
// ┌───────┐
// │content│
// └───────┘

This example shows a Block with padding left and right (Padding::horizontal). Notice the two spaces before and after the content.

use ratatui::widgets::{Block, Padding};

Block::bordered().padding(Padding::horizontal(2));
// Renders
// ┌───────────┐
// │  content  │
// └───────────┘

pub fn inner(&self, area: Rect) -> Rect

Compute the inner area of a block based on its border visibility rules.

Examples

Draw a block nested within another block

use ratatui::{widgets::Block, Frame};

let outer_block = Block::bordered().title("Outer");
let inner_block = Block::bordered().title("Inner");

let outer_area = frame.area();
let inner_area = outer_block.inner(outer_area);

frame.render_widget(outer_block, outer_area);
frame.render_widget(inner_block, inner_area);
// Renders
// ┌Outer────────┐
// │┌Inner──────┐│
// ││           ││
// │└───────────┘│
// └─────────────┘

Trait Implementations

impl<'a> Clone for Block<'a>

fn clone(&self) -> Block<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Block<'a>

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

Formats the value using the given formatter.

impl<'a> Default for Block<'a>

fn default() -> Block<'a>

Returns the “default value” for a type.

impl<'a> Hash for Block<'a>

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<'a> PartialEq for Block<'a>

fn eq(&self, other: &Block<'a>) -> 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<'a> Styled for Block<'a>

type Item = Block<'a>

fn style(&self) -> Style

Returns the style of the object.

fn set_style<S: Into<Style>>(self, style: S) -> Self::Item

Sets the style of the object.

impl Widget for Block<'_>

fn render(self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl WidgetRef for Block<'_>

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl<'a> Eq for Block<'a>

impl<'a> StructuralPartialEq for Block<'a>