Struct Paragraph

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

A widget to display some text.

It is used to display a block of text. The text can be styled and aligned. It can also be wrapped to the next line if it is too long to fit in the given area.

The text can be any type that can be converted into a Text. By default, the text is styled with Style::default(), not wrapped, and aligned to the left.

The text can be wrapped to the next line if it is too long to fit in the given area. The wrapping can be configured with the wrap method. For more complex wrapping, consider using the Textwrap crate.

The text can be aligned to the left, right, or center. The alignment can be configured with the alignment method or with the left_aligned, right_aligned, and centered methods.

The text can be scrolled to show a specific part of the text. The scroll offset can be set with the scroll method.

The text can be surrounded by a Block with a title and borders. The block can be configured with the block method.

The style of the text can be set with the style method. This style will be applied to the entire widget, including the block if one is present. Any style set on the block or text will be added to this style. See the Style type for more information on how styles are combined.

Note: If neither wrapping or a block is needed, consider rendering the Text, Line, or Span widgets directly.

Example

use ratatui::{
    layout::Alignment,
    style::{Style, Stylize},
    text::{Line, Span},
    widgets::{Block, Paragraph, Wrap},
};

let text = vec![
    Line::from(vec![
        Span::raw("First"),
        Span::styled("line", Style::new().green().italic()),
        ".".into(),
    ]),
    Line::from("Second line".red()),
    "Third line".into(),
];
Paragraph::new(text)
    .block(Block::bordered().title("Paragraph"))
    .style(Style::new().white().on_black())
    .alignment(Alignment::Center)
    .wrap(Wrap { trim: true });

Implementations

impl<'a> Paragraph<'a>

pub fn new<T>(text: T) -> Self

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

Creates a new Paragraph widget with the given text.

The text parameter can be a Text or any type that can be converted into a Text. By default, the text is styled with Style::default(), not wrapped, and aligned to the left.

Examples

use ratatui::{
    style::{Style, Stylize},
    text::{Line, Text},
    widgets::Paragraph,
};

let paragraph = Paragraph::new("Hello, world!");
let paragraph = Paragraph::new(String::from("Hello, world!"));
let paragraph = Paragraph::new(Text::raw("Hello, world!"));
let paragraph = Paragraph::new(Text::styled("Hello, world!", Style::default()));
let paragraph = Paragraph::new(Line::from(vec!["Hello, ".into(), "world!".red()]));

pub fn block(self, block: Block<'a>) -> Self

Surrounds the Paragraph widget with a Block.

Example

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

let paragraph = Paragraph::new("Hello, world!").block(Block::bordered().title("Paragraph"));

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

Sets the style of the entire widget.

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

This applies to the entire widget, including the block if one is present. Any style set on the block or text will be added to this style.

Example

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

let paragraph = Paragraph::new("Hello, world!").style(Style::new().red().on_white());

pub const fn wrap(self, wrap: Wrap) -> Self

Sets the wrapping configuration for the widget.

See Wrap for more information on the different options.

Example

use ratatui::widgets::{Paragraph, Wrap};

let paragraph = Paragraph::new("Hello, world!").wrap(Wrap { trim: true });

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

Set the scroll offset for the given paragraph

The scroll offset is a tuple of (y, x) offset. The y offset is the number of lines to scroll, and the x offset is the number of characters to scroll. The scroll offset is applied after the text is wrapped and aligned.

Note: the order of the tuple is (y, x) instead of (x, y), which is different from general convention across the crate.

For more information about future scrolling design and concerns, see RFC: Design of Scrollable Widgets on GitHub.

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

Set the text alignment for the given paragraph

The alignment is a variant of the Alignment enum which can be one of Left, Right, or Center. If no alignment is specified, the text in a paragraph will be left-aligned.

Example

use ratatui::{layout::Alignment, widgets::Paragraph};

let paragraph = Paragraph::new("Hello World").alignment(Alignment::Center);

pub const fn left_aligned(self) -> Self

Left-aligns the text in the given paragraph.

Convenience shortcut for Paragraph::alignment(Alignment::Left).

Examples

use ratatui::widgets::Paragraph;

let paragraph = Paragraph::new("Hello World").left_aligned();

pub const fn centered(self) -> Self

Center-aligns the text in the given paragraph.

Convenience shortcut for Paragraph::alignment(Alignment::Center).

Examples

use ratatui::widgets::Paragraph;

let paragraph = Paragraph::new("Hello World").centered();

pub const fn right_aligned(self) -> Self

Right-aligns the text in the given paragraph.

Convenience shortcut for Paragraph::alignment(Alignment::Right).

Examples

use ratatui::widgets::Paragraph;

let paragraph = Paragraph::new("Hello World").right_aligned();

pub fn line_count(&self, width: u16) -> usize

Calculates the number of lines needed to fully render.

Given a max line width, this method calculates the number of lines that a paragraph will need in order to be fully rendered. For paragraphs that do not use wrapping, this count is simply the number of lines present in the paragraph.

This method will also account for the Block if one is set through Self::block.

Note: The design for text wrapping is not stable and might affect this API.

Example

use ratatui::{widgets::{Paragraph, Wrap}};

let paragraph = Paragraph::new("Hello World")
    .wrap(Wrap { trim: false });
assert_eq!(paragraph.line_count(20), 1);
assert_eq!(paragraph.line_count(10), 2);

Stability

This API is marked as unstable and is only available when the unstable-rendered-line-info crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time. The tracking issue is: https://github.com/ratatui/ratatui/issues/293.

pub fn line_width(&self) -> usize

Calculates the shortest line width needed to avoid any word being wrapped or truncated.

Accounts for the Block if a block is set through Self::block.

Note: The design for text wrapping is not stable and might affect this API.

Example

use ratatui::{widgets::Paragraph};

let paragraph = Paragraph::new("Hello World");
assert_eq!(paragraph.line_width(), 11);

let paragraph = Paragraph::new("Hello World\nhi\nHello World!!!");
assert_eq!(paragraph.line_width(), 14);

Stability

This API is marked as unstable and is only available when the unstable-rendered-line-info crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time. The tracking issue is: https://github.com/ratatui/ratatui/issues/293.

Trait Implementations

impl<'a> Clone for Paragraph<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Paragraph<'a>

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

Formats the value using the given formatter.

impl<'a> Default for Paragraph<'a>

fn default() -> Paragraph<'a>

Returns the “default value” for a type.

impl<'a> Hash for Paragraph<'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 Paragraph<'a>

fn eq(&self, other: &Paragraph<'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 Paragraph<'a>

type Item = Paragraph<'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 Paragraph<'_>

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 Paragraph<'_>

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 Paragraph<'a>

impl<'a> StructuralPartialEq for Paragraph<'a>