Struct ratatui::text::Text

pub struct Text<'a> {
    pub lines: Vec<Line<'a>>,
    pub style: Style,
    pub alignment: Option<Alignment>,
}

A string split over one or more lines.

Text is used wherever text is displayed in the terminal and represents one or more Lines of text. When a Text is rendered, each line is rendered as a single line of text from top to bottom of the area. The text can be styled and aligned.

Constructor Methods

• Text::raw creates a Text (potentially multiple lines) with no style.
• Text::styled creates a Text (potentially multiple lines) with a style.
• Text::default creates a Text with empty content and the default style.

Conversion Methods

• Text::from creates a Text from a String.
• Text::from creates a Text from a &str.
• Text::from creates a Text from a Cow<str>.
• Text::from creates a Text from a Span.
• Text::from creates a Text from a Line.
• Text::from creates a Text from a Vec<Line>.
• Text::from_iter creates a Text from an iterator of items that can be converted into Line.

Setter Methods

These methods are fluent setters. They return a Text with the property set.

• Text::style sets the style of this Text.
• Text::alignment sets the alignment for this Text.
• Text::left_aligned sets the alignment to Alignment::Left.
• Text::centered sets the alignment to Alignment::Center.
• Text::right_aligned sets the alignment to Alignment::Right.

Iteration Methods

• Text::iter returns an iterator over the lines of the text.
• Text::iter_mut returns an iterator that allows modifying each line.
• Text::into_iter returns an iterator over the lines of the text.

Other Methods

• Text::width returns the max width of all the lines.
• Text::height returns the height.
• Text::patch_style patches the style of this Text, adding modifiers from the given style.
• Text::reset_style resets the style of the Text.
• Text::push_line adds a line to the text.
• Text::push_span adds a span to the last line of the text.

Examples

Creating Text

A Text, like a Line, can be constructed using one of the many From implementations or via the Text::raw and Text::styled methods. Helpfully, Text also implements core::iter::Extend which enables the concatenation of several Text blocks.

use std::{borrow::Cow, iter};

use ratatui::prelude::*;

let style = Style::new().yellow().italic();
let text = Text::raw("The first line\nThe second line").style(style);
let text = Text::styled("The first line\nThe second line", style);
let text = Text::styled(
    "The first line\nThe second line",
    (Color::Yellow, Modifier::ITALIC),
);

let text = Text::from("The first line\nThe second line");
let text = Text::from(String::from("The first line\nThe second line"));
let text = Text::from(Cow::Borrowed("The first line\nThe second line"));
let text = Text::from(Span::styled("The first line\nThe second line", style));
let text = Text::from(Line::from("The first line"));
let text = Text::from(vec![
    Line::from("The first line"),
    Line::from("The second line"),
]);
let text = Text::from_iter(iter::once("The first line").chain(iter::once("The second line")));

let mut text = Text::default();
text.extend(vec![
    Line::from("The first line"),
    Line::from("The second line"),
]);
text.extend(Text::from("The third line\nThe fourth line"));

Styling Text

The text’s Style is used by the rendering widget to determine how to style the text. Each Line in the text will be styled with the Style of the text, and then with its own Style. Text also implements Styled which means you can use the methods of the Stylize trait.

let text = Text::from("The first line\nThe second line").style(Style::new().yellow().italic());
let text = Text::from("The first line\nThe second line")
    .yellow()
    .italic();
let text = Text::from(vec![
    Line::from("The first line").yellow(),
    Line::from("The second line").yellow(),
])
.italic();

Aligning Text

The text’s Alignment can be set using Text::alignment or the related helper methods. Lines composing the text can also be individually aligned with Line::alignment.

let text = Text::from("The first line\nThe second line").alignment(Alignment::Right);
let text = Text::from("The first line\nThe second line").right_aligned();
let text = Text::from(vec![
    Line::from("The first line").left_aligned(),
    Line::from("The second line").right_aligned(),
    Line::from("The third line"),
])
.centered();

Rendering Text

Text implements the Widget trait, which means it can be rendered to a Buffer or to a Frame.

// within another widget's `render` method:
let text = Text::from("The first line\nThe second line");
text.render(area, buf);

// within a terminal.draw closure:
let text = Text::from("The first line\nThe second line");
frame.render_widget(text, area);

Rendering Text with a Paragraph Widget

Usually apps will use the Paragraph widget instead of rendering a Text directly as it provides more functionality.

let text = Text::from("The first line\nThe second line");
let paragraph = Paragraph::new(text)
    .wrap(Wrap { trim: true })
    .scroll((1, 1))
    .render(area, buf);

Fields

lines: Vec<Line<'a>>

The lines that make up this piece of text.

style: Style

The style of this text.

alignment: Option<Alignment>

The alignment of this text.

Implementations

impl<'a> Text<'a>

pub fn raw<T>(content: T) -> Self

where T: Into<Cow<'a, str>>,

Create some text (potentially multiple lines) with no style.

Examples

Text::raw("The first line\nThe second line");
Text::raw(String::from("The first line\nThe second line"));

pub fn styled<T, S>(content: T, style: S) -> Self

where T: Into<Cow<'a, str>>, S: Into<Style>,

Create some text (potentially multiple lines) with a style.

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

Examples

let style = Style::default()
    .fg(Color::Yellow)
    .add_modifier(Modifier::ITALIC);
Text::styled("The first line\nThe second line", style);
Text::styled(String::from("The first line\nThe second line"), style);

pub fn width(&self) -> usize

Returns the max width of all the lines.

Examples

let text = Text::from("The first line\nThe second line");
assert_eq!(15, text.width());

pub fn height(&self) -> usize

Returns the height.

Examples

let text = Text::from("The first line\nThe second line");
assert_eq!(2, text.height());

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

Sets the style of this text.

Defaults to Style::default().

Note: This field was added in v0.26.0. Prior to that, the style of a text was determined only by the style of each Line contained in the line. For this reason, this field may not be supported by all widgets (outside of the ratatui crate itself).

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

Examples

let mut line = Text::from("foo").style(Style::new().red());

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

Patches the style of this Text, adding modifiers from the given style.

This is useful for when you want to apply a style to a text that already has some styling. In contrast to Text::style, this method will not overwrite the existing style, but instead will add the given style’s modifiers to this text’s style.

Text also implements Styled which means you can use the methods of the Stylize trait.

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

This is a fluent setter method which must be chained or used as it consumes self

Examples

let raw_text = Text::styled("The first line\nThe second line", Modifier::ITALIC);
let styled_text = Text::styled(
    String::from("The first line\nThe second line"),
    (Color::Yellow, Modifier::ITALIC),
);
assert_ne!(raw_text, styled_text);

let raw_text = raw_text.patch_style(Color::Yellow);
assert_eq!(raw_text, styled_text);

Examples found in repository

examples/user_input.rs (line 220)

fn ui(f: &mut Frame, app: &App) {
    let vertical = Layout::vertical([
        Constraint::Length(1),
        Constraint::Length(3),
        Constraint::Min(1),
    ]);
    let [help_area, input_area, messages_area] = vertical.areas(f.size());

    let (msg, style) = match app.input_mode {
        InputMode::Normal => (
            vec![
                "Press ".into(),
                "q".bold(),
                " to exit, ".into(),
                "e".bold(),
                " to start editing.".bold(),
            ],
            Style::default().add_modifier(Modifier::RAPID_BLINK),
        ),
        InputMode::Editing => (
            vec![
                "Press ".into(),
                "Esc".bold(),
                " to stop editing, ".into(),
                "Enter".bold(),
                " to record the message".into(),
            ],
            Style::default(),
        ),
    };
    let text = Text::from(Line::from(msg)).patch_style(style);
    let help_message = Paragraph::new(text);
    f.render_widget(help_message, help_area);

    let input = Paragraph::new(app.input.as_str())
        .style(match app.input_mode {
            InputMode::Normal => Style::default(),
            InputMode::Editing => Style::default().fg(Color::Yellow),
        })
        .block(Block::default().borders(Borders::ALL).title("Input"));
    f.render_widget(input, input_area);
    match app.input_mode {
        InputMode::Normal =>
            // Hide the cursor. `Frame` does this by default, so we don't need to do anything here
            {}

        InputMode::Editing => {
            // Make the cursor visible and ask ratatui to put it at the specified coordinates after
            // rendering
            #[allow(clippy::cast_possible_truncation)]
            f.set_cursor(
                // Draw the cursor at the current position in the input field.
                // This position is can be controlled via the left and right arrow key
                input_area.x + app.cursor_position as u16 + 1,
                // Move one line down, from the border to the input line
                input_area.y + 1,
            );
        }
    }

    let messages: Vec<ListItem> = app
        .messages
        .iter()
        .enumerate()
        .map(|(i, m)| {
            let content = Line::from(Span::raw(format!("{i}: {m}")));
            ListItem::new(content)
        })
        .collect();
    let messages =
        List::new(messages).block(Block::default().borders(Borders::ALL).title("Messages"));
    f.render_widget(messages, messages_area);
}

pub fn reset_style(self) -> Self

Resets the style of the Text.

Equivalent to calling patch_style(Style::reset()).

This is a fluent setter method which must be chained or used as it consumes self

Examples

let text = Text::styled(
    "The first line\nThe second line",
    (Color::Yellow, Modifier::ITALIC),
);

let text = text.reset_style();
assert_eq!(Style::reset(), text.style);

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

Sets the alignment for this text.

Defaults to: None, meaning the alignment is determined by the rendering widget. Setting the alignment of a Text generally overrides the alignment of its parent Widget.

Alignment can be set individually on each line to override this text’s alignment.

Examples

Set alignment to the whole text.

let mut text = Text::from("Hi, what's up?");
assert_eq!(None, text.alignment);
assert_eq!(
    Some(Alignment::Right),
    text.alignment(Alignment::Right).alignment
)

Set a default alignment and override it on a per line basis.

let text = Text::from(vec![
    Line::from("left").alignment(Alignment::Left),
    Line::from("default"),
    Line::from("default"),
    Line::from("right").alignment(Alignment::Right),
])
.alignment(Alignment::Center);

Will render the following

left
  default
  default
      right

pub fn left_aligned(self) -> Self

Left-aligns the whole text.

Convenience shortcut for Text::alignment(Alignment::Left). Setting the alignment of a Text generally overrides the alignment of its parent Widget, with the default alignment being inherited from the parent.

Alignment can be set individually on each line to override this text’s alignment.

Examples

let text = Text::from("Hi, what's up?").left_aligned();

pub fn centered(self) -> Self

Center-aligns the whole text.

Convenience shortcut for Text::alignment(Alignment::Center). Setting the alignment of a Text generally overrides the alignment of its parent Widget, with the default alignment being inherited from the parent.

Alignment can be set individually on each line to override this text’s alignment.

Examples

let text = Text::from("Hi, what's up?").centered();

Examples found in repository

examples/colors_rgb.rs (line 149)

    fn render(self, area: Rect, buf: &mut Buffer) {
        #[allow(clippy::enum_glob_use)]
        use Constraint::*;
        let [top, colors] = Layout::vertical([Length(1), Min(0)]).areas(area);
        let [title, fps] = Layout::horizontal([Min(0), Length(8)]).areas(top);
        Text::from("colors_rgb example. Press q to quit")
            .centered()
            .render(title, buf);
        self.fps_widget.render(fps, buf);
        self.colors_widget.render(colors, buf);
    }

pub fn right_aligned(self) -> Self

Right-aligns the whole text.

Convenience shortcut for Text::alignment(Alignment::Right). Setting the alignment of a Text generally overrides the alignment of its parent Widget, with the default alignment being inherited from the parent.

Alignment can be set individually on each line to override this text’s alignment.

Examples

let text = Text::from("Hi, what's up?").right_aligned();

pub fn iter(&self) -> Iter<'_, Line<'a>>

Returns an iterator over the lines of the text.

pub fn iter_mut(&mut self) -> IterMut<'_, Line<'a>>

Returns an iterator that allows modifying each line.

pub fn push_line<T: Into<Line<'a>>>(&mut self, line: T)

Adds a line to the text.

line can be any type that can be converted into a Line. For example, you can pass a &str, a String, a Span, or a Line.

Examples

let mut text = Text::from("Hello, world!");
text.push_line(Line::from("How are you?"));
text.push_line(Span::from("How are you?"));
text.push_line("How are you?");

pub fn push_span<T: Into<Span<'a>>>(&mut self, span: T)

Adds a span to the last line of the text.

span can be any type that is convertible into a Span. For example, you can pass a &str, a String, or a Span.

Examples

let mut text = Text::from("Hello, world!");
text.push_span(Span::from("How are you?"));
text.push_span("How are you?");

Trait Implementations

impl<'a> Clone for Text<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Text<'a>

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

Formats the value using the given formatter.

impl<'a> Default for Text<'a>

fn default() -> Text<'a>

Returns the “default value” for a type.

impl Display for Text<'_>

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

Formats the value using the given formatter.

impl<'a, T> Extend<T> for Text<'a>

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

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a> From<&'a Masked<'_>> for Text<'a>

fn from(masked: &'a Masked<'_>) -> Self

Converts to this type from the input type.

impl<'a> From<&'a str> for Text<'a>

fn from(s: &'a str) -> Self

Converts to this type from the input type.

impl<'a> From<Cow<'a, str>> for Text<'a>

fn from(s: Cow<'a, str>) -> Self

Converts to this type from the input type.

impl<'a> From<Line<'a>> for Text<'a>

fn from(line: Line<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<Masked<'a>> for Text<'a>

fn from(masked: Masked<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<Span<'a>> for Text<'a>

fn from(span: Span<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<String> for Text<'a>

fn from(s: String) -> Self

Converts to this type from the input type.

impl<'a> From<Vec<Line<'a>>> for Text<'a>

fn from(lines: Vec<Line<'a>>) -> Self

Converts to this type from the input type.

impl<'a, T> FromIterator<T> for Text<'a>

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

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a> Hash for Text<'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> IntoIterator for &'a Text<'a>

type Item = &'a Line<'a>

The type of the elements being iterated over.

type IntoIter = Iter<'a, Line<'a>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut Text<'a>

type Item = &'a mut Line<'a>

The type of the elements being iterated over.

type IntoIter = IterMut<'a, Line<'a>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for Text<'a>

type Item = Line<'a>

The type of the elements being iterated over.

type IntoIter = IntoIter<<Text<'a> as IntoIterator>::Item>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> PartialEq for Text<'a>

fn eq(&self, other: &Text<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Styled for Text<'a>

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

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

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

Available on crate feature unstable-widget-ref only.

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

impl<'a> StructuralPartialEq for Text<'a>