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.

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

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::new()
    .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 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;
use ratatui::widgets::Block;

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

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

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;
use ratatui::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──────┐│
// ││           ││
// │└───────────┘│
// └─────────────┘

Returns the argument unchanged.

Calls U::from(self).

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