Struct BlockCopy item path

Creates a new block with no Borders or Padding.

Create a new block with all borders shown

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

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

Adds a title to the block using the default position.

The position of the title is determined by the title_position field of the block, which defaults to Top. This can be changed using the Block::title_position method. For explicit positioning, use Block::title_top or Block::title_bottom.

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 Line 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;
use ratatui::widgets::Block;

Block::bordered()
    .title("Title")
    .title(Line::from("Left").left_aligned())
    .title(Line::from("Right").right_aligned())
    .title(Line::from("Center").centered());

§See also

Titles attached to a block can have default behaviors. See

• Block::title_style
• Block::title_alignment

§History

In previous releases of Ratatui this method accepted Into<Title> instead of Into<Line>. We found that storing the position in the block and the alignment in the line better reflects the intended use of the block and its titles. See https://github.com/ratatui/ratatui/issues/738 for more information.

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┐
// │                                  │
// └──────────────────────────────────┘

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┘

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>).

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;
use ratatui::text::Line;
use ratatui::widgets::Block;

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

Sets the default TitlePosition for all block titles.

§Example

This example positions all titles on the bottom by default. The “top” title explicitly sets its position to Top, so it is not affected. The “foo” and “bar” titles will be positioned at the bottom.

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

Block::bordered()
    .title_position(TitlePosition::Bottom)
    .title("foo") // will be at the bottom
    .title_top("top") // will be at the top
    .title("bar"); // will be at the bottom

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};
use ratatui::widgets::Block;
Block::bordered().border_style(Style::new().blue());

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};
use ratatui::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

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

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╮
// │     │
// ╰─────╯

Sets the symbols used to display the border as a ratatui_core::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╗
// ║     ║
// ╚═════╝

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  │
// └───────────┘

Sets the block’s MergeStrategy for overlapping characters, defaulting to Replace.

Changing the strategy to Exact or Fuzzy collapses border characters that intersect with any previously rendered borders.

For more information and examples, see the collapse borders recipe and MergeStrategy docs.

§Example

use ratatui::symbols::merge::MergeStrategy;

// Given several blocks with plain borders (1)
Block::bordered();
// and other blocks with thick borders (2) which are rendered on top of the first
Block::bordered()
    .border_type(BorderType::Thick)
    .merge_borders(MergeStrategy::Exact);

Rendering these blocks with MergeStrategy::Exact or MergeStrategy::Fuzzy will collapse the borders, resulting in a clean layout without connected borders.

┌───┐    ┌───┐  ┌───┲━━━┓┌───┐
│   │    │ 1 │  │   ┃   ┃│   │
│ 1 │    │ ┏━┿━┓│ 1 ┃ 2 ┃│ 1 │
│   │    │ ┃ │ ┃│   ┃   ┃│   │
└───╆━━━┓└─╂─┘ ┃└───┺━━━┛┢━━━┪
    ┃   ┃  ┃ 2 ┃         ┃   ┃
    ┃ 2 ┃  ┗━━━┛         ┃ 2 ┃
    ┃   ┃                ┃   ┃
    ┗━━━┛                ┗━━━┛

Computes the inner area of a block after subtracting space for borders, titles, and padding.

§Examples

Draw a block nested within another block

use ratatui::Frame;
use ratatui::widgets::Block;

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──────┐│
// ││           ││
// │└───────────┘│
// └─────────────┘

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.